# grid_class module

Module containing the Population grid class object.

Here all the functionality of a Population object is defined.

Useful for the user to understand the functionality, but copying functionality isn’t recommended except if you know what you are doing

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: uncomment and implement the HPC functionality

  - 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: Create a designated dict for results

class `binarycpython.utils.grid.``Population`

  Bases: `object`

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

  `Moe_di_Stefano_2017`(options=None)

    Function to handle setting the user input settings, set up the data and load that into interpolators and then set the distribution functions

    Takes a dictionary as its only argument

  `add_grid_variable`(name, longname, valuerange, resolution, spacingfunc, probdist, dphasevol, parameter_name, gridtype='centred', branchpoint=0, precode=None, condition=None)

    Function to add grid variables to the grid_options.

    The execution of the grid generation will be through a nested for loop. Each of the grid variables will get create a deeper for loop.

    The real function that generates the numbers will get written to a new file in the TMP_DIR, and then loaded imported and evaluated. beware that if you insert some destructive piece of code, it will be executed anyway. Use at own risk.

    Tasks:

      - TODO: Fix this complex function.

    Parameters

      - name (`str`) –

        name of parameter. This is evaluated as a parameter and you can use it throughout the rest of the function

        Examples

        name = ‘lnm1’

      - longname (`str`) –

        Long name of parameter

        Examples

        longname = ‘Primary mass’

      - range –

        Range of values to take. Does not get used really, the spacingfunction is used to get the values from

        Examples

        range = [math.log(m_min), math.log(m_max)]

      - resolution (`str`) –

        Resolution of the sampled range (amount of samples). TODO: check if this is used anywhere

        Examples

        resolution = resolution[“M_1”]

      - spacingfunction –

        Function determining how the range is sampled. You can either use a real function, or a string representation of a function call. Will get written to a file and then evaluated.

        Examples

        spacingfunction = “const(math.log(m_min), math.log(m_max), {})”.format(resolution[‘M_1’])

      - precode (`Optional`[`str`]) –

        Extra room for some code. This code will be evaluated within the loop of the sampling function (i.e. a value for lnm1 is chosen already)

        Examples

        precode = ‘M_1=math.exp(lnm1);’

      - probdist (`str`) –

        Function determining the probability that gets assigned to the sampled parameter

        Examples

        probdist = ‘Kroupa2001(M_1)*M_1’

      - dphasevol (`Union`[`str`, `int`]) –

        part of the parameter space that the total probability is calculated with. Put to -1 if you want to ignore any dphasevol calculations and set the value to 1 .. rubric:: Examples

        dphasevol = ‘dlnm1’

      - condition (`Optional`[`str`]) –

        condition that has to be met in order for the grid generation to continue .. rubric:: Examples

        condition = ‘self.grid_options[‘binary’]==1’

      - gridtype (`str`) – Method on how the value range is sampled. Can be either ‘edge’ (steps starting at the lower edge of the value range) or ‘centred’ (steps starting at lower edge + 0.5 * stepsize).

    Return type

      `None`

  `evolve`()

    Entry point function of the whole object. From here, based on the settings, we set up a SLURM or CONDOR grid, or if no setting is given we go straight to evolving the population

    There are no direct arguments to this function, rather it is based on the grid_options settings:

      grid_options[‘slurm’]: integer Boolean whether to use a slurm_grid evolution grid_options[‘condor’]: integer Boolean whether to use a condor_grid evolution

    If neither of the above is set, we continue without using HPC routines (that doesn’t mean this cannot be run on a server with many cores)

    Returns an dictionary containing the analytics of the run TODO: change the way this is done. Slurm & CONDOR should probably do this different

    Return type

      `None`

  `evolve_single`(clean_up_custom_logging_files=True)

    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

  `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)

    Function that exports the all_info to a JSON file

    Tasks:
      - TODO: if any of the values in the dicts here is of a not-serialisable form, then we

          need to change that to a string or something so, use a recursive function that goes over the all_info dict and finds those that fit

      - 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

    Return type

      `Optional`[`str`]

  `parse_cmdline`()

    Function to handle settings values via the command line. 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.

    Tasks:

      - TODO: remove the need for –cmdline

    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)

    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`()

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

  `return_binary_c_version_info`(parsed=False)

    Function that returns the version information of binary_c

  `return_population_settings`()

    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)

    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

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

      - or custom_options (grid_options) –

    Return type

      `None`

  `set_moe_di_stefano_settings`(options=None)

    Function to set user input configurations for the moe & di Stefano methods

    If nothing is passed then we just use the default options

  `write_binary_c_calls_to_file`(output_dir=None, output_filename=None, include_defaults=False)

    Function that loops over the grid code and writes the generated parameters to a file. In the form of a command line call

    Only useful when you have a variable grid as system_generator. MC wouldn’t be that useful

    Also, make sure that in this export there are the basic parameters like m1,m2,sep, orb-per, ecc, probability etc.

    On default this will write to the datadir, if it exists

    Tasks:

      - TODO: test this function

      - TODO: make sure the binary_c_python .. output file has a unique name

    Parameters

      - output_dir (`Optional`[`str`]) – (optional, default = None) directory where to write the file to. If custom_options[‘data_dir’] is present, then that one will be used first, and then the output_dir

      - output_filename (`Optional`[`str`]) – (optional, default = None) filename of the output. If not set it will be called “binary_c_calls.txt”

      - include_defaults (`bool`) – (optional, default = None) whether to include the defaults of binary_c in the lines that are written. Beware that this will result in very long lines, and it might be better to just export the binary_c defaults and keep them in a separate file.

    Returns

      filename that was used to write the calls to

    Return type

      filename