Population grid code options
============================
The following chapter contains all grid code options, along with their descriptions
There are 1 options that are not described yet.


Public options
--------------
The following options are meant to be changed by the user.


| **C_auto_logging**: Dictionary containing parameters to be logged by binary_c. The structure of this dictionary is as follows: the key is used as the headline which the user can then catch. The value at that key is a list of binary_c system parameters (like star[0].mass)

| **C_logging_code**: Variable to store the exact code that is used for the custom_logging. In this way the user can do more complex logging, as well as putting these logging strings in files.

| **amt_cores**: The amount of cores that the population grid will use. The multiprocessing is useful but make sure to figure out how many logical cores the machine has. The core is multi processed, not multi threaded, and will gain no extra speed when amt_cores exceeds the amount of logical cores. Input: int

| **combine_ensemble_with_thread_joining**: Boolean flag on whether to combine everything and return it to the user or if false: write it to data_dir/ensemble_output_{population_id}_{thread_id}.json

| **condor**: Int flag whether to use a condor type population evolution. Not implemented yet.

| **custom_logging_func_memaddr**: Memory address where the custom_logging_function is stored. Input: int

| **do_dry_run**: Whether to do a dry run to calculate the total probability for this run

| **ensemble_factor_in_probability_weighted_mass**: Flag to multiply all the ensemble results with 1/probability_weighted_mass

| **evolution_type**: Variable containing the type of evolution used of the grid. Multiprocessing or linear processing

| **failed_systems_threshold**: Variable storing the maximum amount of systems that are allowed to fail before logging their command line arguments to failed_systems log files

| **gridcode_filename**: Filename for the grid code. Set and used by the population object. TODO: allow the user to provide their own function, rather than only a generated function.

| **log_args**: Boolean to log the arguments. Unused 

| **log_args_dir**: Directory to log the arguments to. Unused

| **log_file**: Log file for the population object. Unused

| **log_runtime_systems**: Whether to log the runtime of the systems . Each systems run by the thread is logged to a file and is stored in the tmp_dir. (1 file per thread). Don't use this if you are planning to run a lot of systems. This is mostly for debugging and finding systems that take long to run. Integer, default = 0. if value is 1 then the systems are logged

| **m&s_options**: Internal variable that holds the M&S options. Don't write to this your self

| **max_queue_size**: Maximum size of the queue that is used to feed the processes. Don't make this too big! Default: 1000. Input: int

| **modulo**: No description available yet

| **multiplicity_fraction_function**: Which multiplicity fraction function to use. 0: None, 1: Arenou 2010, 2: Rhagavan 2010, 3: M&S 2017

| **parse_function**: Function that the user can provide to handle the output the binary_c. This function has to take the arguments (self, output). Its best not to return anything in this function, and just store stuff in the grid_options['results'] dictionary, or just output results to a file

| **repeat**: Factor of how many times a system should be repeated. Consider the evolution splitting binary_c argument for supernovae kick repeating.

| **run_zero_probability_system**: Whether to run the zero probability systems. Default: True. Input: Boolean

| **slurm**: Int flag whether to use a Slurm type population evolution.

| **source_file_filename**: Variable containing the source file containing lines of binary_c command line calls. These all have to start with binary_c.

| **tmp_dir**: Directory where certain types of output are stored. The grid code is stored in that directory, as well as the custom logging libraries. Log files and other diagnostics will usually be written to this location, unless specified otherwise

| **verbosity**: Verbosity of the population code. Default is 0, by which only errors will be printed. Higher values will show more output, which is good for debugging.

| **weight**: Weight factor for each system. The calculated probability is multiplied by this. If the user wants each system to be repeated several times, then this variable should not be changed, rather change the _repeat variable instead, as that handles the reduction in probability per system. This is useful for systems that have a process with some random element in it.

Moe & di Stefano sampler options
--------------------------------
The following options are meant to be changed by the user.


| **Mmin**: Minimum stellar mass

| **multiplicity_model**: 
	multiplicity model (as a function of log10M1)
	
	You can use 'Poisson' which uses the system multiplicity
	given by Moe and maps this to single/binary/triple/quad
	fractions.
	
	Alternatively, 'data' takes the fractions directly
	from the data, but then triples and quadruples are
	combined (and there are NO quadruples).
	

| **multiplicity_modulator**: 
	[single, binary, triple, quadruple]
	
	e.g. [1,0,0,0] for single stars only
	     [0,1,0,0] for binary stars only
	
	defaults to [1,1,0,0] i.e. singles and binaries
	

| **normalize_multiplicities**: 
	'norm': normalise so the whole population is 1.0
	        after implementing the appropriate fractions
	        S/(S+B+T+Q), B/(S+B+T+Q), T/(S+B+T+Q), Q/(S+B+T+Q)
	        given a mix of multiplicities, you can either (noting that
	        here (S,B,T,Q) = appropriate modulator * model(S,B,T,Q) )
	        note: if you only set one multiplicity_modulator
	        to 1, and all the others to 0, then normalising
	        will mean that you effectively have the same number
	        of stars as single, binary, triple or quad (whichever
	        is non-zero) i.e. the multiplicity fraction is ignored.
	        This is probably not useful except for
	        testing purposes or comparing to old grids.
	
	'raw'   : stick to what is predicted, i.e.
	          S/(S+B+T+Q), B/(S+B+T+Q), T/(S+B+T+Q), Q/(S+B+T+Q)
	          without normalisation
	          (in which case the total probability < 1.0 unless
	          all you use single, binary, triple and quadruple)
	
	'merge' : e.g. if you only have single and binary,
	          add the triples and quadruples to the binaries, so
	          binaries represent all multiple systems
	          ...
	          *** this is canonical binary population synthesis ***
	
	          It only takes the maximum multiplicity into account,
	          i.e. it doesn't multiply the resulting array by the multiplicity modulator again.
	          This prevents the resulting array to always be 1 if only 1 multiplicity modulator element is nonzero
	
	          Note: if multiplicity_modulator == [1,1,1,1]. this option does nothing (equivalent to 'raw').
	

| **q_high_extrapolation_method**: Same as q_low_extrapolation_method

| **q_low_extrapolation_method**: 
	q extrapolation (below 0.15) method
	    none
	    flat
	    linear2
	    plaw2
	    nolowq
	

| **ranges**: 

| **resolutions**: 

Private options
---------------
The following options are not meant to be changed by the user, as these options are used and set internally by the object itself. The description still is provided, but just for documentation purposes.


| **_actually_evolve_system**: Whether to actually evolve the systems of just act as if. for testing. used in _process_run_population_grid

| **_binary_c_config_executable**: Full path of the binary_c-config executable. This options is not used in the population object.

| **_binary_c_dir**: Director where binary_c is stored. This options are not really used

| **_binary_c_executable**: Full path to the binary_c executable. This options is not used in the population object.

| **_binary_c_shared_library**: Full path to the libbinary_c file. This options is not used in the population object

| **_commandline_input**: String containing the arguments passed to the population object via the command line. Set and used by the population object.

| **_count**: Counter tracking which system the generator is on.

| **_custom_logging_shared_library_file**: filename for the custom_logging shared library. Used and set by the population object

| **_end_time_evolution**: Variable storing the end timestamp of the population evolution. Set by the object itself

| **_errors_exceeded**: Variable storing a Boolean flag whether the amount of errors was higher than the set threshold (failed_systems_threshold). If True, then the command line arguments of the failing systems will not be stored in the failed_system_log files.

| **_errors_found**: Variable storing a Boolean flag whether errors by binary_c are encountered.

| **_evolution_type_options**: List containing the evolution type options.

| **_failed_count**: Variable storing the amount of failed systems.

| **_failed_prob**: Variable storing the total probability of all the failed systems

| **_failed_systems_error_codes**: List storing the unique error codes raised by binary_c of the failed systems

| **_grid_variables**: Dictionary storing the grid_variables. These contain properties which are accessed by the _generate_grid_code function

| **_loaded_ms_data**: Internal variable storing whether the M&S data has been loaded into memory

| **_main_pid**: Main process ID of the master process. Used and set by the population object.

| **_population_id**: Variable storing a unique 32-char hex string.

| **_probtot**: Total probability of the population.

| **_set_ms_grid**: Internal flag whether the M&S grid has been loaded

| **_start_time_evolution**: Variable storing the start timestamp of the population evolution. Set by the object itself.

| **_store_memaddr**: Memory address of the store object for binary_c.

| **_system_generator**: Function object that contains the system generator function. This can be from a grid, or a source file, or a Monte Carlo grid.

| **_total_mass_run**: To count the total mass that thread/process has ran

| **_total_probability_weighted_mass_run**: To count the total mass * probability for each system that thread/process has ran

| **_total_starcount**: Variable storing the total amount of systems in the generator. Used and set by the population object.

| **_zero_prob_stars_skipped**: Internal counter to track how many systems are skipped because they have 0 probability

