Population class module

Module containing the Population grid class object.

Here all the functionality of a Population object is defined.

TODO: the save_snapshots and save_snapshot, are they actually distinct?

Tasks:
  • TODO: add functionality to ‘on-init’ set arguments

  • TODO: add functionality to return the initial_abundance_hash

  • TODO: add functionality to return the isotope_hash

  • TODO: add functionality to return the isotope_list

  • TODO: add functionality to return the nuclear_mass_hash

  • TODO: add functionality to return the nuclear_mass_list

  • TODO: add functionality to return the source_list

  • TODO: add functionality to return the ensemble_list

  • TODO: consider spreading the functions over more files.

  • TODO: type the private functions

  • TODO: fix the correct object types for the default values of the bse_options

  • TODO: think of a clean and nice way to unload and remove the custom_logging_info library from memory (and from disk)

  • TODO: think of a nice way to remove the loaded grid_code/ generator from memory.

TODO: Some of the methods that we have defined in the (mixin) class are designed to be used as a portal to information (return_binary_c_version_info for example.) THe current design is that they are all instance methods, but that is not always necessary. We can decorate them with @staticmethod, or @classmethod to make it easier to use them (https://realpython.com/instance-class-and-static-methods-demystified/)

class binarycpython.utils.grid.Population(**kwargs)[source]

Bases: analytics, cache, dataIO, distribution_functions, grid_logging, grid_options_defaults, gridcode, HPC, metadata, Moe_di_Stefano_2017, spacing_functions, version_info

Population Object. Contains all the necessary functions to set up, run and process a population of systems

clean()[source]

Clean the contents of the population object so it can be reused.

Calling _pre_run_setup()

TODO: decide to deprecate this function

Return type

None

evolve()[source]

Entry point function of the whole object. From here, based on the settings, we set up a grid and (probably) evolve the population.

There are no direct arguments to this function, the grid_options contain all the relevant settings.

Return type

None

Returns

a dictionary containing the analytics of the run.

evolve_single(clean_up_custom_logging_files=True)[source]

Function to run a single system, based on the settings in the grid_options

The output of the run gets returned, unless a parse function is given to this function.

Parameters

clean_up_custom_logging_files (bool) – whether the clean up all the custom_logging files.

Return type

Any

Returns

either returns the raw binary_c output, or whatever the parse_function does

exit(code=None, message=True, flush=True, stacktrace=False)[source]

Exit function: use this to exit from a Population object. Really it’s just a wrapper for sys.exit() to return the correct exit code, but also to post a message (if message is True, default is True) and perhaps a stacktrace (if stacktrace is True, default is False).

export_all_info(use_datadir=True, outfile=None, include_population_settings=True, include_binary_c_defaults=True, include_binary_c_version_info=True, include_binary_c_help_all=True, ensure_ascii=False, indent=4)[source]

Function that exports the all_info to a JSON file

Tasks:
  • TODO: Fix to write things to the directory. which options do which etc

  • TODO: there’s flawed logic here. rewrite this part pls

  • TODO: consider actually just removing the whole ‘output to file’ part and let the

    user do this.

Parameters
  • include_population_settings (bool) – whether to include the population_settings (see function return_population_settings)

  • include_binary_c_defaults (bool) – whether to include a dict containing the binary_c parameters and their default values

  • include_binary_c_version_info (bool) – whether to include a dict containing all the binary_c version info (see return_binary_c_version_info)

  • include_binary_c_help_all (bool) – whether to include a dict containing all the information about the binary_c parameters (see get_help_all)

  • use_datadir (bool) – Boolean whether to use the custom_options[‘data_dir’] to write the file to. If the custom_options[“base_filename”] is set, the output file will be called <custom_options[“base_filename”]>_settings.json. Otherwise a file called simulation_<date+time>_settings.json will be created

  • outfile (Optional[str]) – if use_datadir is false, a custom filename will be used

  • ensure_ascii (str) – the ensure_ascii flag passed to json.dump and/or json.dumps (Default: False)

  • indent (int) – indentation passed to json.dump and/or json.dumps (default 4)

Return type

Optional[str]

jobID()[source]

Function to return the job ID number of this process as a string.

Normal processes return their process ID (PID) HPC processes return whatever HPC_jobID() gives.

parse_cmdline()[source]

Function to handle settings values via the command line in the form x=y, w=z, etc.

Best to be called after all the .set(..) lines, and just before the .evolve() is called

If you input any known parameter (i.e. contained in grid_options, defaults/bse_options or custom_options), this function will attempt to convert the input from string (because everything is string) to the type of the value that option had before.

The values of the bse_options are initially all strings, but after user input they can change to ints.

The value of any new parameter (which will go to custom_options) will be a string.

Return type

None

return_all_info(include_population_settings=True, include_binary_c_defaults=True, include_binary_c_version_info=True, include_binary_c_help_all=True)[source]

Function that returns all the information about the population and binary_c

Parameters
  • include_population_settings (bool) – whether to include the population_settings (see function return_population_settings)

  • include_binary_c_defaults (bool) – whether to include a dict containing the binary_c parameters and their default values

  • include_binary_c_version_info (bool) – whether to include a dict containing all the binary_c version info (see return_binary_c_version_info)

  • include_binary_c_help_all (bool) – whether to include a dict containing all the information about the binary_c parameters (see get_help_all)

Return type

dict

Returns

dictionary containing all, or part of, the above dictionaries

return_binary_c_defaults()[source]

Function that returns the defaults of the binary_c version that is used.

return_population_settings()[source]

Function that returns all the options that have been set.

Can be combined with JSON to make a nice file.

Return type

dict

Returns

dictionary containing “bse_options”, “grid_options”, “custom_options”

set(**kwargs)[source]

Function to set the values of the population. This is the preferred method to set values of functions, as it provides checks on the input.

the bse_options will get populated with all the those that have a key that is present in the self.defaults

the grid_options will get updated with all the those that have a key that is present in the self.grid_options

If neither of above is met; the key and the value get stored in a custom_options dict.

Parameters
  • parameters (via kwargs all the arguments are either set to binary_c) –

  • custom_options (grid_options or) –

Return type

None

was_killed()[source]

Function to determine if the process was killed. Returns True if so, false otherwise.