-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathm_common.f90
8963 lines (8082 loc) · 461 KB
/
m_common.f90
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
!> @file m_common.f90
!! This module defines common global parameters and objects for the AHA Model.
!! It also contains a general overview of the AHA Model in Doxygen notation.
!! @author Sergey Budaev <[email protected]>
!! @author Jarl Giske <[email protected]>
!! @date 2016-2017
!-------------------------------------------------------------------------------
! $Id$
!-------------------------------------------------------------------------------
! Note: This is the starting main Doxygen documentation page. It should be
! subdivided using @section @subsection @subsubsection tags rather than
! the Markdown ###-style.
!> @mainpage The AHA Model: Evolution of decision making and behaviour
!> @section intro_aha_intro Overview of The AHA Model
!! This is a large scale simulation model (under development) that implements
!! a general **decision-making architecture** in **evolutionary agents**. Each
!! agent is programmed as a whole virtual organism including the genome,
!! rudimentary physiology, the hormonal system, a cognitive architecture and
!! behavioural repertoire. They "live" in a stochastic spatially explicit
!! virtual environment with physical gradients, predators and prey. The primary
!! aim of the whole modelling machinery is to understand the evolution of
!! decision making mechanisms, personality, emotion and behavioural plasticity
!! within a realistic ecological framework. An object-oriented approach coupled
!! with a highly modular design not only allows to cope with increasing layers
!! of complexity inherent in such a model system but also provides a framework
!! for the system generalizability to a wide variety of systems. We also use
!! a "physical-machine-like" implementation philosophy and a coding standard
!! integrating the source code with parallel detailed documentation that
!! increases understandability, replicability and reusability of this model
!! system.
!!
!> The cognitive architecture of the organism is based on a set of
!! motivational (emotional) systems that serves as a common currency for
!! decision making. Then, the decision making is based on **predictive
!! assessment** of external and internal stimuli as well as the agent's own
!! motivational (emotional) state. The agent makes a subjective assessment
!! and selects, from the available repertoire, the behaviour that would reduce
!! the expected motivational (emotional) arousal. Thus, decision making is
!! based on predicting one's own internal state. As such, the decision-making
!! architecture integrates motivation, emotion, and a very simplistic model
!! of consciousness.
!!
!! The **purpose** of the AHA model is to investigate a general framework for
!! modelling proximate decision-making and behavior. From this we will
!! investigate adaptive goal-directed behaviour that is both guided by the
!! external environment and still is endogeneously generated.
!!
!! Other research topics include individual differences, personality as well
!! as consequences of emotion and personality to population ecology.
!!
!! We think that understanding and modelling complex adaptive behaviour
!! requires both extraneous (environmental) factors and stimuli as well as
!! endogeneous mechanisms that produce the behaviour. Explicit proximate
!! representation of the motivation and emotion systems, self-prediction can
!! be an important component in linking environment, genes, physiology,
!! behavior, personality and consciousness.
!!
!! - The AHA! Project Development Pages: http://ahamodel.uib.no
!! - Building blocks of the AHA Model: @ref aha_builblocks_main
!! - The Cognitive Architecture of the agent: @ref aha_buildblocks_cogn_arch
!! .
!!
!! Fortran is used due to its simplicity and efficiency. For example, check out
!! this paper:
!! [Why physicists still use Fortran?](http://www.moreisdifferent.com/2015/07/16/why-physicsts-still-use-fortran).
!!
!! Main features of modern Fortran that are used in the AHA model code
!! are briefly outlined in the
!! [README_NF](http://ahamodel.uib.no/doxydoc/md__r_e_a_d_m_e__n_f.html) .
!!
!> @section intro_version Version information
!! This is the model version information parsed from the main Subversion
!! repository https://svn.uib.no/aha-fortran or Bitbucket Mercurial-based
!! repository https://bitbucket.org/ahaproject/hedg2_01 (the latter is
!! currently used just as a mirror of the Subversion branch).
!! @verbatim
!! $Id: m_common.f90 851df748b488 2018/02/17 20:25:54 sergey $
!! @endverbatim
!! Version information is also saved as two variables that can be passed to
!! the logger (see commondata::logger_init()) and outputs and file names:
!! - commondata::svn_version_string, full version string as above;
!! - commondata::svn_version, version number (hex id).
!! .
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!!
!> @section intro_main Working with the Model
!! A "Getting Started" introduction is available in the
!! [README.md](http://ahamodel.uib.no/doxydoc/md__r_e_a_d_m_e.html) file.
!!
!> @subsection intro_overview_modules Overview of the AHA Fortran modules
!! The Modelling framework is composed of two separate components:
!! - [HEDTOOLS](http://ahamodel.uib.no/doc/HEDTOOLS.pdf)
!! (also [mirror at bitbucket](https://bitbucket.org/teg_uib/hedtools)),
!! modelling utilities and tools implemented as portable Fortran
!! modules, not object-oriented, that have general applicability and are
!! used for data conversion, output, random number generation and
!! execution logging. HEDTOOLS modules are designed such that they can be
!! used in many different simulation projects, not only the AHA model;
!! - @ref intro_aha_intro "The AHA model", an object oriented evolutionary
!! agents simulation framework implementing reusable module components.
!! @image html aha_modules.svg "Overview of AHA Fortran modules"
!! @image latex aha_modules.eps "Overview of AHA Fortran modules" width=14cm
!!
!> @subsection intro_running Running the model
!! Building and running the mode is based on the GNU Make system.
!! - To **build** the model from the source code issue:
!! @code{.sh}
!! make
!! @endcode
!! - To build and **run** the model issue this command:
!! @code{.sh}
!! make run
!! @endcode
!! - **Delete** all build-related, data and temporary files:
!! @code{.sh}
!! make distclean
!! @endcode
!! - Get a quick **help** from the make system:
!! @code{.sh}
!! make help
!! @endcode
!! - The compiler can be provided via `FC` variable, e.g.
!! @code{.sh}
!! make run FC=ifort
!! @endcode
!! - Building with debug symbols is controlled by setting the `DEBUG` variable.
!! @code{.sh}
!! make run FC=ifort DEBUG=1
!! @endcode
!! .
!! See @ref Makefile for build configuration. To get more information on GNU
!! Make see [AHA Modelling Tools Manual](http://ahamodel.uib.no/doc/ar01s13.html),
!! [Using Microsoft Visual Studio](http://ahamodel.uib.no/doc/ar01s14.html) and
!! [Using Code::Blocks IDE](http://ahamodel.uib.no/doc/ar01s15.html).
!!
!> @subsection intro_environ_vars Environment variables
!! The model makes use of several environment variables to control
!! certain global aspects of the execution. These variables have the `AHA_`
!! prefix and are listed below.
!! - `AHA_DEBUG=TRUE` sets the @ref intro_debug_mode "debug mode";
!! - `AHA_SCREEN=YES` sets logger to write to the standard output in addition
!! to the log file;
!! - `AHA_DEBUG_PLOTS=YES` enables generation of debug plots;
!! - `AHA_ZIP_FILES=YES` enables background compression of big output
!! data files;
!! - `AHA_CHECK_EXTERNALS=NO` disables checking for external executable
!! modules (this is a workaround against Intel Fortran compiler bug).
!! .
!! They are described in details in the `commondata::system_init()` section.
!! **Setting** the environment variable on different platforms:
!! **Linux/Unix:**
!! @code{.sh}
!! export AHA_DEBUG=1
!! @endcode
!! **Windows:**
!! @code{.sh}
!! set AHA_DEBUG=1
!! @endcode
!! **Checking** if the environment variable is set and what is it value
!! On Unix/Linux:
!! @code{.sh}
!! echo $AHA_DEBUG
!! @endcode
!! On Windows
!! @code{.sh}
!! echo %AHA_DEBUG%
!! @endcode
!! To check if any of the above environment variables are set is easy on Linux:
!! @code{.sh}
!! env | grep AHA_
!! @endcode
!!
!> @subsection intro_debug_mode The DEBUG mode
!! The protected global variable `IS_DEBUG` (commondata::is_debug) sets
!! up the **debug mode** of execution. The debug mode results in huge
!! amount of output and logs that significantly slows down execution.
!! Debug mode can be set using the environment variable
!! `AHA_DEBUG=1`, `AHA_DEBUG=YES` or `AHA_DEBUG=TRUE`.
!> Debug mode can also be set by setting the runtime **command line**
!! parameter to `DEBUG`, `DEBUG=1`, `DEBUG=YES` or `DEBUG=TRUE`
!! to the model executable, e.g.
!! @code{.sh}
!! ./MODEL.exe DEBUG
!! @endcode
!! This runtime command line parameter is automatically set if the model
!! is started using the DEBUG variable for the GNU Make:
!! @code{.sh}
!! make run DEBUG=1
!! @endcode
!! *Build* Note also that `DEBUG` with make build command
!! @code{.sh}
!! make DEBUG=1
!! @endcode
!! will build the executable for the model in the debug mode also. All
!! compiler optimisations are turned off (`-O0`), debugger symbols (`-g`) and
!! tracebacks are enabled, various compiler error checking options and
!! warnings are also enabled, along with extended runtime checks.
!!
!! Notably, the Intel Fortran compiler enables initialisation of variables
!! with the signalling NaNs (`-init=snan`). Any operations on non-initialised
!! variable(s) would then result in the runtime crash with traceback, making
!! it easier to catch non-initialised variables.
!!
!! Normal build without setting `DEBUG`, in contrast, enables various compiler
!! optimisations making the executable run faster.
!! @code{.sh}
!! make
!! @endcode
!! Notably, with the Intel Fortran compiler, the model is built with automatic
!! parallelisation (`-parallel`), so whole array operations, `do concurrent`
!! and `pure` and `elemental` functions are run in the
!! [multi-threaded mode](http://ahamodel.uib.no/intel/hh_goto.htm?index.htm#GUID-29986DD5-C17F-49BB-AC9B-365B077C3909.html)
!! whenever the compiler is "sure" that these operations can be safely
!! performed.
!! See the @ref Makefile for specific compiler and debugging options and the
!! [GNU make](http://ahamodel.uib.no/doc/ar01s13.html) for a general overview of
!! the system. A overview of Intel Fortran parallel processing options can be
!! found
!! [here](http://ahamodel.uib.no/intel/hh_goto.htm#GUID-1E91DFFD-D7CD-4AF5-B911-7E5D1CCDBBA5.html)
!! and [here](http://ahamodel.uib.no/intel/hh_goto.htm?index.htm#GUID-06B54325-1C5C-41E7-A9CD-0E3A8542DC05.html).
!!
!! Combining the shell environment variable `AHA_DEBUG` and the `DEBUG` make
!! variable allows to control how the model executable is build and run.
!! For example, *building* it in *non-debug* mode, i.e. with all the
!! optimisations for fast (and possibly multi-threaded) execution:
!! @code{.sh}
!! make
!! @endcode
!! can be combined with *running* the model in the *debug* mode:
!! @code{.sh}
!! export AHA_DEBUG=YES
!! make run
!! @endcode
!! In such a case, the model is built and executed in the "fast" optimised
!! and possibly multi-threaded mode, but still prints all the numerous
!! debugging outputs into the logger.
!!
!! The system initialisation procedure commondata::system_init() and
!! commondata::logger_init() provide more details on initialisation and
!! logging.
!!
!> @subsection intro_overview_lockfile The lock file
!! At the start of the simulation, the program creates an empty **lock file**
!! defined by commondata::lock_file. The lock file is created at the end of
!! commondata::system_init() and and is deleted by the procedure
!! commondata::system_halt().
!!
!! The lock file indicates that the simulation is (still) running and could be
!! used by various scripts, cron jobs etc to make sure the simulation is
!! finished. For example, a script can check from time to time if the lock
!! file exists and if not, issue a command to zip all data outputs and transfer
!! them to a remote analysis server.
!!
!> @subsection intro_overview_files_csv Output numerical data
!! Data could be output from the model. The standard format for data output is
!! [CSV](http://ahamodel.uib.no/doc/ar01s08.html). Its advantage is that it is
!! based on plain text and is human readable nut can be easily imported into
!! spreadsheets and statistical packages. The most straightforward use for CSV
!! is for vector-based data and two-dimensional matrices, including sets of
!! vectors (e.g. 'variables'/columns with 'observations'/rows).
!!
!! CSV output is based on the [CSV_IO](http://ahamodel.uib.no/doc/ar01s08.html)
!! module in [HEDTOOLS](http://ahamodel.uib.no/doc/). There is also an object
!! oriented wrapper for CSV_IO: @ref file_io.
!!
!! The model also includes a few standardised CSV output procedures for saving
!! various characteristics for a whole population of agents:
!! - the_population::population::save_csv() -- save various condition data;
!! - the_population::population::save_genomes_csv() -- save the complete genome
!! data of the agents;
!! - the_population::population::save_memory_csv() -- save the perceptual and
!! emotional memory stacks of the agents;
!! - the_population::population::save_movements_csv() -- save the latest
!! movement history of the agents.
!! - the_population::population::save_behaviour_csv() -- save the behaviour
!! history of the agents: successive labels of behaviours executed.
!! .
!! Additionally, the genetic algorithm subroutine
!! the_evolution::generations_loop_ga() implements a sub-procedure
!! - @ref generation_stats_record_write() -- produces various generation-wise
!! statistics, such as the number of surviving agents, average body mass
!! etc.
!! .
!!
!! The following procedures output the properties of the @ref the_environment
!! at a particular time step:
!! - the_environment::food_resource::save_csv() -- saves all the (stochastic)
!! food items that compose the the_environment::food_resource.
!! - the_environment::habitat::save_predators_csv --saves all the (possibly
!! stochastic) predators that are implemented within the habitat.
!! .
!!
!! @subsection intro_descriptors The Model descriptors
!! The model includes several descriptors that can be used for descriptive
!! notes on the model.
!! - commondata::model_name -- model name: a short name of the model;
!! - commondata::model_descr -- model description: a longer, one line
!! description of the model;
!! - The Model Abstract -- A brief text that can span several lines of text
!! and is kept in a separate file with the name defined by the
!! commondata::model_abstract_file parameter. If this file is absent,
!! model description is used.
!! .
!! These descriptors can appear in the model logger output and form parts of
!! the output data files.
!!
!! In particular, because the Model Abstract is stored in a separate text file,
!! it can contain dynamically updated information, such as the latest version
!! control message log output. Subversion and Mercurial commit hooks can be
!! used to implement such a functionality.
!!
!! To append version information (Subversion) to the Model Abstract file
!! manually do this:
!! @code
!! svn log -l1 >> abstract.txt
!! @endcode
!!
!> @subsection intro_style_rules Coding and documenting style
!! Using a consistent coding style increases the readability and
!! understandability of the program. It is also easier to search and locate
!! specific parts. For example, using specific rules for version control
!! commit messages make it easier to find specific changes by using regular
!! expression syntax. The coding rules for the AHA model are relatively light.
!!
!> @subsubsection intro_coding_style Fortran coding style
!! - Clean, readable and understandable code is much better than "tricky" but
!! more computationally efficient code.
!! - Obsolete, outdated and non-standard (e.g. vendor extensions) features
!! of the Fortran language should *never* be used.
!! - Very modern Fortran features (e.g. many F2008 and F2015) not well
!! supported by the available compilers should be avoided whenever possible.
!! - Portability is crucial: the model should be easy to build and run using
!! different compilers, GNU free software *gfortran* is the compiler of
!! priority.
!! - Frequent checking for errors (and even *possible* errors) is important;
!! correct computation has much higher priority than just speed.
!! - Use generic programming techniques (e.g. optional arguments, generic
!! interfaces) for higher extensibility.
!! - Always use explicit `intent` declared for all subroutines and functions.
!! - The line length should not exceed 80 characters; use continuation lines
!! and indents to make the structure clear.
!! - Spaces (not tabs) are used for indentation, standard indent is 2
!! characters.
!! - Use *lowercase* names for all local and Fortran intrinsic
!! objects.
!! - Global variables (not constants) should be in "CamelCase".
!! - Public or local *constants* (that are not changed) are in
!! UPPERCASE.
!! - External or library objects, e.g. those from the HEDTOOLS are in
!! UPPERCASE
!! - Module names are UPPERCASE, class names are UPPERCASE.
!! - Spatial objects (`SPATIAL` and `SPATIAL_MOVING`) use
!! `position` to *set* spatial position and `location` to
!! *get* it.
!! - `create` method is used to create and initialise an
!! empty object (e.g. `SPATIAL` with missing coordinates),
!! should not take other parameters and must be elemental
!! (so cannot include calls to random);
!! - `make` or `build` method is used to create a working object
!! with random initialisation etc.
!! .
!! See the [AHA Modelling Tools Manual](http://ahamodel.uib.no/doc/) for more
!! details (http://ahamodel.uib.no/doc/HEDTOOLS.pdf).
!!
!! The [README_NF](http://ahamodel.uib.no/doxydoc/md__r_e_a_d_m_e__n_f.html)
!! provides a brief outline of the main features of modern Fortran (F2003/2008)
!! that are used in the model code.
!!
!> @subsubsection intro_commit_style Version control style
!! - Commit messages noting specific subroutines or functions should
!! include the names of these procedures in parentheses:
!! @code{.sh}
!! svn ci -m "hope function (hope) now accepts arbitrary raw grid arrays"
!! @endcode
!! - Commit messages chenging only the Doxygen comments should start with
!! 'doc:', e.g.
!! @code{.sh}
!! svn ci -m "doc: still notes render poorly, try top put to return"
!! @endcode
!! .
!> @subsubsection intro_document_style Doxygen self-document style
!! - If something is changed in the *code*, the documentation comments
!! should also be checked for *correspondence with the code*, Doxygen
!! comments should *always* reflect the logic of the code and should
!! be never outdated.
!! - Document procedure purpose and brief implementation in the
!! over-the-procedure header comment block.
!! - *Local variables* are **not** in the Doxygen tags unless they
!! are very important, then include full paragraph description.
!! - Porting and F2008 compatibility notes and warnings are not in
!! the Doxygen tags unless they are very important.
!! - Unimportant implementation notes can be documented within
!! the body of the procedure *without* Doxygen "`!>`" tags. So they
!! are never parsed.
!! - *Important* implementation details are fully documented in
!! Doxygen tags. So they can be rendered if `HIDE_IN_BODY_DOCS` is
!! `NO`.
!! - Implementation details within the procedure body should be under
!! the level 3 headers enclosed in `###`:
!! @code
!! !> ### Implementation details ###
!! @endcode
!! - Full Fortran variable object hierarchy for instantiated objects must be
!! as normal text, i.e. **not enclosed in reverse single quotes** (as
!! verbatim code), because percent sign is not escaped and parsed wrongly
!! then:
!! @verbatim
!! this\%reprfact_decrement_testosterone
!! @endverbatim
!! not
!! @verbatim
!! `this\%reprfact_decrement_testosterone`
!! @endverbatim
!! or
!! @verbatim
!! this%reprfact_decrement_testosterone
!! @endverbatim
!! or still
!! @verbatim
!! `this%reprfact_decrement_testosterone`
!! @endverbatim
!! as the percent sign disappears in the parsed output.
!! - Reference to other subroutines and functions of the code must
!! be in the C++ style, referring the class/module in **lowercase**:
!! @verbatim
!! !! values resulting from executing this behaviour (`reproduce::do_this()`
!! !! = the_neurobio::reproduce_do_this() method). This is repeated for
!! @endverbatim
!! This makes them appear as cross-links in the parsed document.
!! - Documenting specific implementation procedure for in-type interface
!! name declaration should follow this style (include link to implementation):
!! @verbatim
!! !> Calculate the Euclidean distance between two spatial objects.
!! !! See `the_environment::spatial_distance_3d()`
!! procedure, public :: distance => spatial_distance_3d
!! @endverbatim
!! - Reference to a procedure that is defined within this (being documented)
!! procedure (i.e. below `contains`) is using the hanging `::` notation:
!! @verbatim
!! !! The subjective capture probabilityis calculated by the sub-function
!! !! `::subjective_capture_prob()`.
!! @endverbatim
!! - Documentation sections/subsections/subsubsections with tags are inserted
!! like this:
!! @verbatim
!! !> @subsubsection aha_buildblocks_genome_genome Individual genome
!! @endverbatim
!! They can be referred to in the documentation text using the tag like this:
!! @verbatim
!! !> @ref aha_buildblocks_individual "The individual agent" is also ...
!! @endverbatim
!! - The \@name tag defines an arbitrary **member group** of
!! Doxygen objects. Membership range is defined by the \@{ and
!! \@} tags. But this does not seem to work within `type`
!! definitions to delimiter outer procedure interfaces.
!!
!> @subsection intro_computation_notes Brief notes on computation
!> @subsubsection intro_computation_real Float point computations
!! There are many possible quirks and caveats with the real type (float point)
!! calculations on the computer. The rules of float point computations deviate
!! from the basic arithmetic. The main issue is that real type numbers are
!! represented as bits and have finite and limited precision. Furthermore,
!! numerical precision can deteriorate due to rounding in computations.
!!
!! The precision of the float point number representation in Fortran is
!! controlled by the kind parameter (e.g. `real(kind=some_number`) ).
!!
!! **Numerical precision modes**. In the AHA Model, there are two basic
!! numerical precision modes:
!! - commondata::srp, "Standard Real Precision" for real numbers that is
!! normally used for all computations:
!! @code
!! real(SRP) :: value
!! @endcode
!! @note Note that commondata::srp precision model should be used in most
!! cases.
!! - commondata::hrp, "High Real Precision", an extended precision that is used
!! in a few cases where commondata::srp is not enough for valid computation
!! (insufficient precision or inability to represent huge numbers):
!! @code
!! real(HRP) :: value
!! @endcode
!! Parenthetically, there is also an extended precision integer type defined
!! by commondata::long parameter.
!! .
!!
!! **Constants.** There is also a useful commondata::zero constant, which sets
!! some "minimum distinguishable non-zero" value: it is the smallest real
!! number *E* such that @f$ 1 + E > 1 @f$.
!!
!! The smallest positive real value is defined by the commondata::tiny_srp
!! constant. It is used in the definition of the default numerical tolerance
!! value for high precision calculations:
!! - commondata::tolerance_low_def_srp;
!! - commondata::tolerance_low_def_hrp (the same constant for the high
!! commondata::hrp precision with commondata::tiny_hrp).
!! .
!! @note Note that the commondata::tiny_srp and commondata::tiny_hrp values are
!! much smaller than the commondata::zero parameter. Also, the default
!! tolerance limits commondata::tolerance_low_def_srp and
!! commondata::tolerance_low_def_hrp are also much smaller than the
!! commondata::zero.
!!
!! Because the low tolerance based on the commondata::tiny_srp and
!! commondata::tiny_hrp may be too small and restrictive in many cases, the
!! second set of tolerance limits for low-precision calculations is based on
!! the commondata::zero parameter:
!! - commondata::tolerance_high_def_srp (commondata::srp real);
!! - commondata::tolerance_high_def_hrp (commondata::hrp real).
!! .
!! @note These high tolerance values should be used as the standard `epsilon`
!! in most cases.
!!
!! The default commondata::srp values of these parameters calculated on an
!! x86_64 platform under Linux are (an example only!):
!! @verbatim
!! ZERO: 1.19209290E-07
!! TINY_SRP: 1.17549435E-38
!! TOLERANCE_LOW_DEF_SRP: 5.87747175E-38
!! TOLERANCE_HIGH_DEF_SRP: 1.19209290E-04
!! @endverbatim
!! These constants are reported at the start of the logger output.
!!
!! **Real type equality**. One possible quirk in float point computation
!! involves equality comparison, e.g.
!! @code
!! if ( a == b) then ...
!! @endcode
!! With real type data `a` and `b`, such a condition can lead to unexpected
!! results due to finite precision and even tiny rounding errors: the numbers
!! that are deemed *equal* may in fact *differ* by a tiny fraction leading to
!! `a == b` condition being `FALSE`.
!!
!! Instead of the exact comparison, one should test whether the absolute
!! difference is smaller than than some predefined @f$ \varepsilon @f$
!! tolerance value (in the simplest case):
!! @f[ \left | a-b \right | < \varepsilon @f]
!! The @f$ \varepsilon @f$ is chosen based on the nature of the data and the
!! computational algorithm.
!!
!! The AHA Model framework includes a specific function for testing
!! *approximate equality* of two reals: commondata::float_equal(). With this
!! function, correct comparison is:
!! @code
!! if ( float_equal(a, b, epsilon) ) then ...
!! @endcode
!! There is also a user defined operator "float equality" `.feq.` that works
!! as the commondata::float_equal() function, but uses a fixed default
!! `epsilon` equal to the default tolerance commondata::tolerance_low_def_srp
!! (or commondata::tolerance_low_def_hrp for high precision). Its benefit is
!! that the usage almost coincides with the `==` (`.eq.`) operator usage:
!! @code
!! if ( a .feq. b) then ...
!! @endcode
!! See the backend procedures commondata::float_equal_srp_operator() and
!! commondata::float_equal_hrp_operator() for details.
!! Another similar operator is "approximate equality" `.approx.` has a much
!! higher level of tolerance (larger error accepted)
!! @code
!! if ( a .approx. b) then ...
!! @endcode
!! See the backend procedures commondata::float_approx_srp_operator() and
!! commondata::float_approx_hrp_operator() for details.
!!
!! There is also a function for testing if a real value is approximately equal
!! to zero: commondata::is_near_zero():
!! @code
!! if ( is_near_zero(a) ) then ! correct equivalent of if ( a == 0.0 )
!! @endcode
!!
!! @subsubsection intro_computation_missing Initialisation undefined constants
!! When a variable is created but not yet initialised, its value is
!! "undefined". However, it can take some haphazard values depending on the
!! compiler and the platform. There are special "initialisation" constants
!! defined in @ref commondata that set "missing" or "undefined" variable
!! status: commondata::missing (real) and commondata::unknown (integer).
!! By default, they are set to an unusual negative number -9999, so that any
!! bugs are clearly exposed if a variable inadvertently uses such an
!! "undefined" value.
!!
!! @subsubsection intro_computation_nonpar Nonparametric functions
!! The model in many cases makes use of **nonparametric relationships** between
!! parameters. This is based on the linear and non-linear interpolation
!! procedures implemented in HEDTOOLS:
!! [Interpolation routines](http://ahamodel.uib.no/doc/ar01s07.html#_interpolation_linterpol_ddpinterpol_interp_linear_interp_lagrange)
!!
!! Instead of defining specific function equation linking, say, parameters
!! *X* and *Y*: *Y=f(X)*, the relationship is defined by an explicit **grid**
!! of *X* and *Y* values without specifying any equation.
!!
!! In the simplest two-dimensional case, such a grid is defined by two
!! parameter arrays, for the *abscissa* and the *ordinate* of the nonparametric
!! function. Any values of this function can then be calculated based on a
!! nonlinear interpolation. This makes it very easy to specify various
!! patterns of relationships even when exact function is unknown or not
!! feasible.
!!
!! An example of such a nonparametric function is
!! the_neurobio::gos_global::gos_find().
!!
!> @subsection intro_webresources_model Links for more information
!> **AHA/BEAST Resources:**
!> - AHA Model repository mirror on Bitbucket:
!! https://bitbucket.org/ahaproject/hedg2_01
!! - Full documentation for the AHA Model in PDF:
!! http://ahamodel.uib.no/doxydoc/refman.pdf
!! - HEDTOOLS repository mirror on Bitbucket:
!! https://bitbucket.org/teg_uib/hedtools
!! - HEDTOOLS documentation in HTML format: http://ahamodel.uib.no/doc
!! - HEDTOOLS documentation as a single PDF file:
!! http://ahamodel.uib.no/doc/HEDTOOLS.pdf
!! - Development statistics for the model:
!! http://ahamodel.uib.no/devstat/dir_branches_budaev_HEDG2_01.html
!! - TEG development statistics from Subversion: http://ahamodel.uib.no/devstat
!!
!> **Tools web resources:**
!! - GNU Fortran documentation: https://gcc.gnu.org/onlinedocs/
!! (note that the model code targets features of the pre-version 5 because
!! of their wider availability in Linux repos.)
!! - GNU Fortran 4.9: https://gcc.gnu.org/onlinedocs/gcc-4.9.4/gfortran/
!! .
!! - Intel Fortran compiler documentation: http://ahamodel.uib.no/intel/
!! (note that the model code targets version 17.0)
!! - Automatic parallelisation is [here](http://ahamodel.uib.no/intel/index.htm#GUID-06B54325-1C5C-41E7-A9CD-0E3A8542DC05.html)
!! .
!! - Doxygen documentation: http://www.doxygen.org/
!! - Special tags: http://www.stack.nl/~dimitri/doxygen/manual/commands.html
!! - Formulas: http://www.stack.nl/~dimitri/doxygen/manual/formulas.html
!! .
!! - GNU Make: https://www.gnu.org/software/make/
!! .
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!> @section aha_builblocks_main Building blocks of the AHA model
!> @subsection aha_buildblocks_environ The environment
!! The environment is a full 3D space, that is has the class
!! the_environment::spatial as the elementary base primitive. The
!! the_environment::spatial is a single object that has *X, Y and Z* (depth)
!! coordinates. the_environment::spatial_moving extends the basic
!! the_environment::spatial object by allowing it to move. Furthermore,
!! the_environment::spatial_moving includes a history stack that records the
!! latest history of such a spatial moving object. Examples of spatial moving
!! objects can be food items (the_environment::food_item), predators
!! (the_environment::predator), and more complex objects composed of several
!! the_environment::spatial components like the_environment::environment.
!!
!! The basic environment where the agents "live" is very simplistic in this
!! version of the model. It is just and empty box. The box is delimited by the
!! basic environmental container: the_environment::environment class.
!! The the_environment::habitat class is the ecological "habitat", an extension
!! of the basic the_environment::environment that adds various ecological
!! characteristics and objects such as the_environment::food_resource, array
!! of the_environment::predator objects etc.
!!
!! Normally, the movement of the agent is limited to a specific
!! the_environment::environment container with its own the_environment::habitat.
!! All the habitats that are available for the agents are arranged into a
!! single global public array the_environment::global_habitats_available.
!!
!! @ref aha_buildblocks_individual "The individual agent" is also an extension
!! of the the_environment::spatial class: the_environment::spatial →
!! the_environment::spatial_moving → the_genome::individual_genome → ... →
!! the_population::member_population.
!!
!! @image html aha_environment_diagr.svg
!! @image latex aha_environment_diagr.eps "Environmental objects" width=14cm
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!!
!> @subsection aha_buildblocks_genome The genome structure
!! A brief outline of the genetic architecture, defined in the_genome, is
!! presented on this scheme.
!! - the_genome::gene
!! - the_genome::chromosome
!! - the_genome::individual_genome
!! .
!> @subsubsection aha_buildblocks_genome_gene Gene
!! The agent has genes (class the_genome::gene) that are arranged into
!! chromosomes (class the_genome::chromosome). Each gene also
!! includes an arbitrary number of additive components (see the_genome::gene).
!! @image html aha_genome_01.svg
!! @image latex aha_genome_01.eps "The genome structure" width=14cm
!> @subsubsection aha_buildblocks_genome_chromosome Chromosome
!! Here is a brief outline of the chromosome structure. The chromosomal
!! architecture allows arbitrary ploidity (however haploid is not supported,
!! although can be easily added), i.e. agents with diploid and polyploid
!! genomes can be implemented. Ploidity is defined by a single parameter
!! commondata::chromosome_ploidy.
!!
!> Correspondence between the genotype and the phenotype (hormones,
!! neurobiological modules etc.) is represented by boolean
!! **Gene x Phenotype matrices**. Any arbitrary structure can be implemented,
!! many traits controlled by a single gene, many genes controlling a specific
!! single trait.
!! @anchor aha_buildblocks_gp_matrix_intro
!! @image html aha_genome_02.svg
!! @image latex aha_genome_02.eps "Genotype x phenotype matrix" width=14cm
!!
!! An example of such a structure is the genetic sex determination:
!! commondata::sex_genotype_phenotype.
!!
!! There is a small utility script `tools\gpmatrix.tcl` that assists in
!! automatic production of the Fortran code for such a matrix.
!! @image html img_doxygen_gpmat.png "gpmatrix.tcl utility"
!! @image latex img_doxygen_gpmat.png "gpmatrix.tcl utility" width=12cm
!! @remark Windows distribution for Tcl/Tk language is obtained
!! [here](http://www.activestate.com/activetcl)).
!!
!> @subsubsection aha_buildblocks_genome_genome Individual genome
!! The the_genome::individual_genome class defines the basic higher-level
!! component properties of the whole organism, such as sex (logical type
!! the_genome::individual_genome::sex_is_male), genome size
!! (the_genome::individual_genome::genome_size), individual string "name"
!! of the agent (the_genome::individual_genome::genome_label) etc.
!!
!! The the_genome::individual_genome class also includes such type-bound
!! procedures as the_genome::individual_genome::lives() that gives the agent
!! the "alive" status, the_genome::individual_genome::dies() for making the
!! agent "dead". It also has linked procedures implementing genetic crossover
!! - the_genome::individual_genome::recombine_random(),
!! - the_genome::individual_genome::recombine_partial(),
!! - the_genome::individual_genome::crossover().
!! .
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!!
!> @subsection aha_buildblocks_individual The individual agent
!> The individual agent has a `the_environment::spatial_moving` class as its
!! base (but this class is an extension of the simple the_environment::spatial)
!! and is then composed of several layers by class extensions.
!!
!! Each of these main layers that create the individual agent is defined in
!! separate Fortran module:
!! - genome (the_genome module);
!! - hormones (the_hormones module);
!! - the body characteristics and condition (the_body);
!! - neurobiological architecture (the_neurobio);
!! - behaviour architecture (the_behaviour) that builds on the neurobiology;
!! - finally, the agent is a member of a population (the_individual and
!! the_population::member_population).
!! .
!!
!! @image html aha_individual_class.svg
!! @image latex aha_individual_class.eps "The individual class layers" width=14cm
!!
!! The model code benefits from Fortran intrinsic "elemental" and array-based
!! procedures. To initialise a whole population of random agents (with full
!! object hierarchy) use the the_population::population::init() method:
!! @code
!! call generation_one%init(POPSIZE)
!! @endcode
!! Invocation of the 'init' method calls a whole cascade of various elementary
!! object-bound procedures that create the whole population object.
!!
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!! @subsection aha_buildblocks_visrange Localist interactions
!! The model is based on (almost) fully proximate and localist philosophy.
!! All objects (agents, predators, prey) can obtain information about only
!! those objects that in proximity. No one is considered omniscient. Thus,
!! objects can only interact locally, e.g. the agent can eat only food items
!! that it could see, a predator could only attack agents that are visible to
!! it etc.
!!
!! The distance at which the objects can get information about each other
!! is based on the visibility (visual range). Thus, the agents and predators
!! are considered to be fully visual creatures that can only sense the world
!! with their vision.
!!
!! Visibility, i.e. the distance from which an object can be detected ("seen")
!! depends on the ambient illumination at a specific depth, the area of the
!! object, its contrast etc. Visual range is calculated for the different
!! kinds of objects using the the_environment::visual_range() backend.
!!
!! Examples of the visual range are the visibility distance of an agent
!! the_body::condition::visibility(), food item
!! the_environment::food_item::visibility(), and predator
!! the_environment::predator::visibility().
!!
!! Importantly, the @ref aha_buildblocks_percept "perception" of various
!! kinds of environmental objects by the agent uses the
!! the_environment::visual_range() calculation engine.
!!
!! Furthermore, probabilities of stochastic events typically have non-linear
!! relationships with the visual range. One example is the probability of
!! capture of a food item by the agent. This probability is high in close
!! proximity but strongly reduces at the distance equal to the visual range
!! limit: the_environment::food_item::capture_probability(). Similarly, the
!! risk that the agent is killed by a predator is highest at a small distances
!! and significantly reduces at a distance equal to the visibility limit (i.e.
!! the maximum distance the predator can see the agent):
!! the_neurobio::perception::risk_pred(). A more complex procedure is
!! implemented for the probability of successful reproduction:
!! the_neurobio::appraisal::probability_reproduction().
!!
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!! @subsection aha_buildblocks_cogn_arch The Cognitive Architecture
!! The cognitive architecture of the agent is represented on the scheme below.
!! It includes several functional units, "bundles," each representing specific
!! motivation or emotion state.
!! @note Note that the scheme below includes three such bundles for the states
!! *A*, *B*, *C*. For simplicity, there are also only three stimuli
!! @f$ S_1, S_2, S_3 @f$ .
!!
!> @image html aha_global_scheme_neuroresp.svg "General cognitive architecture of the agent"
!! @image latex aha_global_scheme_neuroresp.eps "General cognitive architecture of the agent" width=14cm
!!
!! **General.** The agent perceives the outer and its own inner environment,
!! obtaining perception (signal) values. The agent also has several motivation
!! (emotional) states, such that only one can be active at any time step of the
!! model. Thus, the states compete for this position. The winning motivation
!! (emotion) becomes the dominant emotional state of the agent, its Global
!! Organismic State. This @ref aha_buildblocks_neurobioflow_gos
!! "Global Organismic States" of the agent determines how the agent weights
!! different options during its decision making process and therefore
!! determines what kind of behaviour (action) it will execute.
!!
!! **Perception and appraisal.** The agent obtains
!! @ref aha_buildblocks_neurobioflow_perc "perceptions" (*P*) from its
!! external and internal environments. These perceptions are fed into the
!! @ref aha_buildblocks_neurobioflow_appr "Appraisal" modules, separate for
!! each of the motivation/emotion state.
!!
!! Here perception signals are first fed into the
!! @ref aha_buildblocks_neuronal_resp "neuronal response functions" (based on
!! the sigmoidal function commondata::gamma2gene()). The neuronal response
!! function is a function of both the perception signal (*P*) and the
!! genome (*G*) of the agent. Perception signal is also distorted by a
!! random Gaussian error. Each neuronal response function returns the neuronal
!! response (*R*) value.
!!
!! The neuronal responses *R* for each stimulus are summed for the same
!! motivation module to get the *primary motivation* values
!! (@f$ M_1 @f$) for this motivational state. These primary motivations can
!! then be subjected to genetic or developmental (e.g. age-related)
!! **modulation**, resulting in the *final motivation* values (@f$ M_{f} @f$).
!! Such modulation could strengthen or weaken the motivation values and
!! therefore shift the outcome of competition between the different
!! motivational states. In absence of modulation @f$ M_1 = M_{f} @f$.
!!
!! **Global Organismic State.** Final motivations (@f$ M_{f} @f$) for different
!! motivations (emotions) are competing, so that the winning state that is
!! characterised by the highest final motivation value becomes the dominant
!! emotional state of the agent: its @ref aha_buildblocks_neurobioflow_gos
!! "Global Organismic State" at the next time step. Additionally, the final
!! motivation value of this state becomes the *GOS arousal* level.
!!
!! The competition mechanism is complex and dynamic. It depends on the
!! current arousal level, such that relatively minor fluctuations in the
!! stimuli and their associated motivation values are ignored and do not
!! result in switching of the GOS to a different state.
!!
!! Furthermore, the relative difference (surplus) that the competing motivation
!! must have to win competition against the current state depends on the
!! current level of GOS arousal. If the current arousal level of the agent is
!! relatively low (motivation or emotion is weak), a competing state must
!! exceed a relatively higher threshold to win. However, if the current arousal
!! level is very high (high motivation or emotion), a competing state can win
!! even if it only slightly exceeds the current arousal level. Thus, the
!! emotional state of the agent is characterised by a degree of continuity or
!! "inertia" and such inetria is lower the higher is the current level of
!! arousal. The dynamic threshold mechanism for GOS competition is described
!! in details in the_neurobio::gos_find_global_state() procedure documentation
!! section.
!!
!! **Attention focus.** Whenever the agent has a specific Global Organismic
!! State, this state also affects the agent's *perception*. All the perception
!! inputs that belong to motivations other than the currently dominant (i.e.
!! the current GOS) are suppressed by *attention weights*. For example, if the
!! motivation *B* is the GOS, all the perception values linked with Motivation
!! *A* and *C* are suppressed. The suppression weights are proportional to the
!! current GOS arousal of the agent.
!!
!! Thus, the attention mechanism effectively filters out or "focus" the agent
!! on the stimuli that are linked with the current dominant emotional state.
!! Moreover, the stronger is the current GOS arousal, the stronger is such
!! attention focusing. Attention weight mechanism is described in details in
!! the the_neurobio::gos_attention_modulate_weights() procedure section.
!!
!! **Perception-to-arousal path.** This process, *perception → neuronal
!! response → motivation → GOS → arousal* is repeated at each time step of the
!! model as the agent acts in (e.g. moves through) its stochastic environment.
!! In effect, the dominant motivational and emotional state of the agent
!! changes adapting to to the latest changes in the inner and external
!! environment.
!!
!! **Self-predictive decision making**. Furthermore, the same processes (and
!! computer code procedures) are also evoked when the agent is *making the
!! decision* about what *behavioural action* to choose at each time step.
!!
!! Basically, the agent predicts what would be its perceptions and, for each
!! of the behavioural action available, runs the same process
!! (perception → neuronal response → motivation → GOS → arousal) and finally
!! selects the behaviour that would result in the lowest predicted GOS arousal.
!! Perceptions in this process are predicted from the agent's internal or
!! local external environment ("fake" perceptions in the `do_this` method for
!! each of the behaviour units). They are also subjected to attention
!! suppression, however, attention weights are transferred from the
!! agent's own current Global Organismic State by
!! the_behaviour::behaviour_base::attention_transfer() method.
!!
!! Thus, decision making of the agent is based on predicting one's own
!! emotional state. The emotional arousal therefore becomes a common currency
!! in decision making. See @ref aha_buildblocks_decision
!! "Predictive decision making" for more details.
!!
!! **Goal directed behaviour.** The cognitive architecture implemented in the
!! AHA model effectively produces goal-directed behaviour in the agents. The
!! "goal" is defined by the evolutionary process, the @ref aha_buildblocks_ga
!! "Genetic Algorighm". Specifically , the target "goal" is to survive, grow,
!! accumulate energy and reproduce. The agents that do best in this respect
!! pass their genes into the next generation.
!!
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!! @subsection aha_buildblocks_ga The Genetic Algorithm
!! @subsubsection aha_buildblocks_ga1 Fixed explicit fitness GA
!! This version of the Genetic Algorithm (GA) is based on an explicitly
!! defined "fitness" value for each individual agent. The evolution then
!! optimises agents with respect to this fitness: only agents with high
!! fitness values pass their genes into the next generations.
!!
!! This algorithm for this kind of GA is simple and is implemented in the
!! the_evolution::generations_loop_ga() procedure:
!! - Initialise the first generation of agents (population) from random
!! genomes. This first generation becomes the "parents".
!! - Start the main GA generations loop
!! - All "parent"-population agents go via the full life cycle
!! (with many time steps), the_population::population::lifecycle_step().
!! - Fixed fitness is calculated for each individual agent showing how good
!! it did during the life cycle by the
!! the_individual::individual_agent::fitness_calc() method.
!! - All agents are sorted according to their fitness by
!! the_population::population::sort_by_fitness().
!! - Some number of the "best fitting" agents (i.e. those with the highest
!! fitness values) are selected for the new generation: their genomes
!! pass to the new "offspring" generation in an unchanged form (i.e.
!! this is an *elitism*-based GA algorithm): the_evolution::selection().
!! - The rest of the offspring population are obtained from the genomes of
!! the best fitting agents, however,
!! - parent's genomes randomly exchange their genetic material,
!! - the resulting offspring genomes are subject to random mutations.
!! .
!! These steps are implemented in the_evolution::mate_reproduce().
!! - This new offspring population now becomes the "parents". A mechanism
!! based on pointer swapping implemented in
!! the_evolution::generations_swap() avoids copying big arrays of agents.
!! .
!! - Finally, the algorithm goes to the next generation loop cycle.
!! .
!!
!! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
!> @subsection aha_buildblocks_lifecycle Life cycle of the agent
!! @subsubsection aha_buildblocks_life_init Initialisation
!! The life cycle of the agent begins with birth. In the first generation of the
!! Genetic Algorithm each agent is initialised from a random genome by calling
!! the the_individual::individual_agent::init() method. This method evokes a
!! cascade of procedures that initialise all levels of the
!! @ref aha_buildblocks_individual "individual agent" object hierarchy.
!!
!! All subsequent generations use pre-existing genomes that are passed from
!! the ancestral agents subject to genetic crossover and mutation. The
!! the_individual::individual_agent::init() procedure has a logical switch that
!! controls if a random genome should be generated.
!!
!! Because the population of agents is an object (class
!! the_population::population), a whole population of agents is initialised
!! by the the_population::population::init() method. After the birth, all
!! agents get random location within their initial the_environment::habitat
!! object by calling the_population::population::scatter_uniform().
!!
!! @subsubsection aha_buildblocks_life_time Life cycle step
!! Then, the agents pass through many time steps (commondata::lifespan).
!! At each time step each agent gets internal and environmental
!! @ref aha_buildblocks_percept "perceptions". Based on these instantaneous
!! perceptions, they obtain their main internal state: the
!! @ref aha_neurobio_flow "Global Organismic State" (GOS). Finally, each agent
!! must make a decision to execute a single specific
!! @ref aha_buildblocks_behaviour "behaviour" depending on its GOS, internal
!! and external environment (@ref aha_buildblocks_percept "perception"). Some
!! examples of such behaviour are eat a food item, approach a conspecific,
!! escape from a predator, move, freeze, migrate to a novel environment,
!! reproduce, etc.
!!
!! Each of the behaviour chosen by the agent has specific consequences and
!! can
!! - affect the agent (e.g. incurs energetic cost, or relocation of the
!! whole agent into a novel environment, the agent is killed if it does not
!! escape a nearby predator),
!! - affect the other agents in proximity (e.g. emigration of an agent could
!! change the risk of predation for other agents by changing the spatial
!! configuration and therefore modifying predation dilution and confusion
!! effects for the agents that remain in place),
!! - affect the external environment (e.g. food item disappears when an agent
!! eat it).
!! .
!!
!! Whenever the agent successfully consumes food items, it grows
!! its mass and length: the_body::condition::mass_grow(),
!! the_body::condition::len_grow().
!! On the other hand, every movement incurs some energetic cost:
!! the_body::condition::cost_swim(). There are also additional costs linked