There are ten flavors of the core simuPOP module: short, long, binary, mutant, and lineage allele modules, and their optimized versions.
Despite of differences in internal memory layout, all these modules have the same interface, although some functions behave differently in terms of functionality and performance.
Standard libraries have detailed debug and run-time validation mechanism to make sure a simulation executes correctly. Whenever something unusual is detected, simuPOP would terminate with detailed error messages. The cost of such run-time validation varies from case to case but can be high under some extreme circumstances. Because of this, optimized versions for all modules are provided. They bypass most parameter checking and run-time validations and will simply crash if things go wrong. It is recommended that you use standard libraries whenever possible and only use the optimized version when performance is needed and you are confident that your simulation is running as expected.
Examples lst_Use_of_standard_module and lst_Use_of_optimized_module demonstrate the differences between standard and optimized modules, by executing two invalid commands. A standard module checks all input values and raises exceptions when invalid inputs are detected. An interactive Python session would catch these exceptions and print proper error messages. In constrast, an optimized module returns erroneous results and or simply crashes when such inputs are given.
Example: Use of standard simuPOP modules
>>> import simuPOP as sim
>>> pop = sim.Population(10, loci=2)
>>> pop.locusPos(10)
Traceback (most recent call last):
File "/var/folders/ys/gnzk0qbx5wbdgm531v82xxljv5yqy8/T/tmpfGL_Ei", line 1, in <module>
#begin_file log/standard.py
IndexError: genoStru.h: 561 absolute locus index (10) out of range of 0 ~ 1
>>> pop.individual(20).setAllele(1, 0)
Traceback (most recent call last):
File "/var/folders/ys/gnzk0qbx5wbdgm531v82xxljv5yqy8/T/tmpfGL_Ei", line 1, in <module>
#begin_file log/standard.py
IndexError: population.h: 573 individual index (20) out of range of 0 ~ 9
Example lst_Use_of_optimized_module also demonstrates how to use the setOptions function in the simuOpt module to control the choice of one of the six simuPOP modules. By specifying one of the values short, long or binaryfor option alleleType, and settingoptimized to True or False, the right flavor of module will be chosen when simuPOP is loaded. In addition, option quiet can be used suppress the banner message when simuPOP is loaded. An alternative method is to set environmental variable SIMUALLELETYPE to short, long or binary to use the standard short, long or binary module, and variable SIMUOPTIMIZED to use the optimized modules. Command line options --optimized can also be used.
Example: Use of optimized simuPOP modules
% python
>>> from simuOpt import setOptions
>>> setOptions(optimized=True, alleleType='long', quiet=True)
>>> import simuPOP as sim
>>> pop = sim.Population(10, loci=[2])
>>> pop.locusPos(10)
1.2731974748756028e-313
>>> pop.individual(20).setAllele(1, 0)
Segmentation fault
simuPOP is capable of executing in multiple threads but it by default only makes use of one thread. If you have a multi-core CPU, it is often beneficial to set the number of threads to 2 or more to take advantage of this feature. The recommended number of threads is usually the number of cores of your CPU but you might want to set it to a lower number to leave room for the execution of other applications. The number of threads used in simuPOP can be controlled in the following ways:
The number of threads a simuPOP session is used will be displayed in the banner message when simuPOP is imported, and can be retrieved through moduleInfo['threads'].
Although simuPOP can usually benefit from the use of multiple cores, certain features of your script might prevent the execution of simuPOP in multiple threads. For example, if your script uses a sex mode of GLOBAL_SEX_SEQUENCE to set the sex of offspring according to the global sequence of sexes (e.g. male, male, female), simuPOP will only use on thread to generate offspring because it is not feasible to assign individual sex from a single source of list across multiple threads.
A complete graphical user interface (GUI) for users to interactively construct evolutionary processes is still in the planning stage. However, some simuPOP classes and functions can make use of a GUI to improve user interaction. For example, a parameter input dialog can be constructed automatically from a parameter specification list, and be used to accept user input if class simuOpt.Params is used to handle parameters. Other examples include a progress bar simuPOP.utils.ProgressBar and a dialog used by function simuPOP.utils.viewVars to display a large number of variables. The most notable feature of the use of GUI in simuPOP is that all functionalities can be achieved without a GUI. For examples, simuOpt.getParam will use a terminal to accept user input interactively and simuPOP.utils.ProgressBar will turn to a text-based progress bar in the non-GUI mode.
The use of GUI can be controlled either globally or Individually. First, a global GUI parameter could be set by environmental variable SIMUGUI, function simuOpt.setOptions(gui) or a command line option --gui of a simuPOP scripts. Allowed values include
Individual classes and functions that could make use a GUI usually have their own gui parameters, which can be set to override global GUI settings. For example, you could force the use of a text-based progress bar by using ProgressBar(gui=False).