Module defining the PSyGrid, the main grid object of POSYDON.

I. CREATING A GRID

  1. One-liner for creating a grid without loading it in memory:

    mygrid = PSyGrid(verbose=True).create(“mysimulations/”, “mygrids/grid1.h5”)

  2. Create a grid and keep it for processing:

    mygrid = PSyGrid() mygrid.create(“MESA_simulations/ZAMS_grid/”, “stored_grids/ZAMS_grid.h5”) print(mygrid)

  3. Store only metadata and initial/final values of runs:

    mygrid = PSyGrid().create(in_dir_path, out_file_path, slim=True)

  4. Various options (see definition of create and GRIDPROPERTIES for more):

    mygrid = PSyGrid().create(in_dir_path, out_file_path,

    overwrite=True, warn=”suppress”, max_number_of_runs=1000, description=”My 1000-run grid.”)

    NOTE: you can use a family of HDF5 files in case of file size restrictions. For example, using mygrid.h5.%d for the path when creating/loading grids, implies that split files will be mygrid.h5.0, mygrid.h5.1, and so on. When overwriting the file, all the family is overwritten (effectively, the files are emptied to avoid remainder split files from previous operations.)

  5. The history/profile data can be downsampled to significantly reduce the size of the grid. There are three downsampling procedures: one combining all data from histories (binary / star 1 / star 2), and two for each star’s profile. The parameters of the downsampling of histories and profiles can be set via the GRIDPROPERTIES dictionary (see below). For example, for history down- sampling, you can set a tolerance level (between 0 and 1) which corresponds to the maximum interpolation error tolerated with respect to the range of the parameters:

    history_DS_error = 0.01.

    Columns to be ignored during the downsampling process are set using the history_DS_exclude parameter. The corresponding parameters for profile

    downsampling are profile_DS_error and profile_DS_exclude.

  6. The input path can be a list of paths to indicate multiple folders with MESA runs. Each of the paths can have wildcard characters to select subfolders or even runs. E.g.: - [“/grid_part1”, “/grid_part2”] - “/grid_part*” - [“/grid/run1”, “/grid/run2*”]

    Note that all provided paths are searched recursively, allowing for hierar- chical organizations of the MESA runs. For example, the parent folder could look like this:

    part_A/

    run1/ run2/

    part_B/

    run3/ run4/

    extra_run1/ extra_run2/

  7. Only one run can be included for a specific set of initial parameters, being identified by the folder name (excluding the _grid_index* part). E.g.,

    reruns/m1_28_m2_11_initial_z_1.42e-02_initial_period_in_days_2_grid_index_0

    will be preferred over

    main/m1_28_m2_11_initial_z_1.42e-02_initial_period_in_days_2_grid_index_102

    if the PSyGrid is created with the appropriate order of input paths:

    mygrid = PSyGrid([“mygrid/main”, “mygrid/reruns”])

    The user is notified through warnings about such substitutions.

  8. To include specific columns from MESA data files, set the grid properties of the form *_saved_columns. For example,

    grid.create(“mygrid/”, “mygrid.h5”,

    star1_history_saved_columns=[“star_mass”])

    By default, the provided columns will be added to the default list. In order to select the exact set of columns, provide them in a tuple instead of list.

II. READING DATA FROM A GRID

mygrid = PSyGrid(“thegrid.h5”) # opens a stored grid

# Indexing… t1 = mygrid[0][“binary_history”][“age”] t3 = mygrid[0].binary_history[“age”]

tenth_run = mygrid[10] if tenth_run[“binary_history”] is None:

print(“No binary history in 10th run.”)

Use .close() method to close the HDF5 file, or delete the grid variable. E.g.

mygrid.close()

or

del mygrid

III. OTHER FUNCTIONS

  1. Printing / logging summary:

    print(mygrid)

    with open(“grid_summary.txt”, “w”) as f:

    f.write(str(mygrid))

  2. In for loop (iter and next are supported too):

    for run in mygrid:

    print(run)

  3. Getting the number of runs:

    n_runs = len(psygrid)

  4. Checking if run index is defined in grid:

    if (13 in grid):

    print(“My good luck lasted for”, grid[13].binary_history.age[-1], “yr”)

  5. Getting list or set of runs (i.e., PSyGridView objects):

    run_lst = list(psygrid) run_set = set(psygrid)

  6. Printing parameters used during the creation of the grid

    print(psygrid.config)

WARNING: reducing reading times when accessing a PSyGrid

When accessing a table in a specific run, e.g.,

mygrid[0].history1

or

for run in mygrid:

do_something_with(run.history1)

the table is loaded from the HDF5 file temporarily. This means that:

myrun.history1.star_mass + myrun.history1.star_mass

loads the table two times! To reduce reading times, store all the tables that are going to be needed more than once in local variables:

myhistory1 = myrun.history1 myhistory1.star_mass + myhistory1.star_mass

class posydon.grids.psygrid.PSyGrid(filepath=None, verbose=False)[source]

Bases: object

Class handling a grid of MESA runs encoded in HDF5 format.

Initialize the PSyGrid, and if filename is provided, open it.

Parameters

  • verbose (bool) – If True, the objects reports by printing to standard output.

  • path (str or None) – If not None, it is the path of the HDF5 file to be loaded.

HR(idx, history='history1', states=False, verbose=False, **kwargs)[source]

Plot the HR diagram of one or more runs.

Parameters

  • idx (int or list of int) – Index or indices of runs to plot.

  • history (str) – Which history is going to be used. The options are: “binary_history”, “history1”, or “history2”.

  • states (bool) – If true the HR diagram shows the stellar state with a color map.

  • verbose (bool) – If True, the object reports by printing to standard output.

  • **kwargs (dict) – Dictionary containing extra visualisation options (cf. PLOT_PROPERTIES in plot_defaults.py).

add_column(colname, array, where='final_values', overwrite=True)[source]

Add a new numerical column in the final values array.

close()[source]

Close the HDF5 file if open.

create(MESA_grid_path, psygrid_path=None, overwrite=False, slim=False, warn='end', fmt='posydon', **grid_kwargs)[source]

Create a new PSyGrid object from a MESA grid and save it on disk.

Parameters

  • MESA_grid_path (str) – The path of the top directory where the input grid is located.

  • psygrid_path (str) – The path of the HDF5 file to be created (or overwritten). If not provided, it is assumed that it was defined during initialization.

  • overwrite (bool) – Whether to overwrite the HDF5 file if it already exists.

  • slim (bool) – If True, only the metadata and initial/final values are stored.

  • warn (str) – How warnings are handled. If “normal”, then warnings are shown when they occur. If “end”, they are collected and shown at the end. If “suppress”, then warnings are not shown at all.

  • **grid_kwargs (dict) – Configuration of the new grid, passed as ddditional arguments.

generate_config(**grid_kwargs)[source]

Store the grid’s configuration in a ConfigFile object.

get_pandas_initial_final()[source]

Convert the initial/final values into a single Pandas dataframe.

load(filepath=None)[source]

Load up a previously created PSyGrid object from an HDF5 file.

Parameters

filepath (str) – Location of the HDF5 file to be loaded. If not provided, assume it was defined during the initialization (argument: filepath).

plot(idx, x_var_str, y_var_str, z_var_str=None, history='binary_history', verbose=False, **kwargs)[source]

Plot a 1D track of x_var_str vs y_var_str.

Parameters

  • idx (int or list of int) – Index or indices of runs to plot.

  • x_var_str (str) – String of values to plot on the x axis. Allowed strings are the one in psygrid.history.dtype.names where “history” needs to be chosen accordingly.

  • y_var_str (str or list of str) – String or list of stringvalues to plot on the y axis. Allowed strings are the one in psygrid.history.dtype.names where “history” needs to be chosen accordingly.

  • z_var_str (str) – String of values to plot on the z axis (displayed with a color). Allowed strings are the one in psygrid.history.dtype.names where “history” needs to be chosen accordingly.

  • history (str) – The x, y, z variables are read from either: “binary_history”, “history1”, “history2”.

  • verbose (bool) – If True, the object reports by printing to standard output.

  • **kwargs (dict) – Dictionary containing extra visualisation options (cf. PLOT_PROPERTIES in plot_defaults.py).

plot2D(x_var_str, y_var_str, z_var_str=None, termination_flag='termination_flag_1', grid_3D=None, slice_3D_var_str=None, slice_3D_var_range=None, grid_4D=None, slice_4D_var_str=None, slice_4D_var_range=None, extra_grid=None, slice_at_RLO=False, MARKERS_COLORS_LEGENDS=None, verbose=False, **kwargs)[source]

Plot a 2D slice of x_var_str vs y_var_str of one or more runs.

Parameters

  • x_var_str (str) – String of the initial value to plot on the x axis. Allowed strings are psygrid.initial_values.dtype.names.

  • y_var_str (str) – String of the initial value to plot on the y axis. Allowed strings are psygrid.initial_values.dtype.names.

  • z_var_str (str) – String of the initial value to plot on the z axis (displayed as a color). Allowed strings are psygrid.final_values.dtype.names, psygrid.history1.dtype.names, psygrid.binary_history.dtype.names.

  • termination_flag (str) – Termination flag to display, allowed values are: “termination_flag_1”, “termination_flag_2”, “termination_flag_3”, “termination_flag_4”, “all”.

  • grid_3D (bool) – If True, the psygrid object is a 3D grid and needs to be sliced.

  • slice_3D_var_str (str) – Variable along which the 3D space will be sliced. Allowed values are psygrid.initial_values.dtype.names.

  • slice_3D_var_range (tuple) – Range between which you want to slice the variable slice_3D_var_str e.g., (2.5,3.).

  • grid_4D (bool) – If True, the psygrid object is a 4D grid and needs to be sliced.

  • slice_4D_var_str (str) – Variable along which the 4D space will be sliced. Allowed values are psygrid.initial_values.dtype.names.

  • slice_4D_var_range (toople) – Range between which you want to slice the variable slice_4D_var_str e.g., (2.5,3.).

  • extra_grid (object or array of objects) – If subset of the grid was rerun a or an extention was added, one can overlay the new psygrid by passing it here.

  • slice_at_RLO (bool) – If True, the object plots the tracks until onset of Roche Lobe overflow.

  • MARKERS_COLORS_LEGENDS (dict) – Each termination flag is associated with a marker shape, size, color and label (cf. MARKERS_COLORS_LEGENDS in plot_defaults.py).

  • verbose (bool) – If True, the object reports by printing to standard output.

  • **kwargs (dict) – Dictionary containing extra visualisation options (cf. PLOT_PROPERTIES in plot_defaults.py.

rerun(path_to_file='./', runs_to_rerun=None, termination_flags=None, new_mesa_flag=None)[source]

Create a CSV file with the PSyGrid initial values to rerun.

This methods allows you to create a CSV file with the psygrid initial values you want to rerun.

Parameters

  • path_to_file (str) – The path to the directory where the new grid.csv file will be saved. If the directory does not exist it will be created.

  • runs_to_rerun (integer array) – Array containing the indecies of the psygrid runs you want to rerun e.g., runs_to_rerun = np.array([2,3])

  • termination_flags (str) – The runs with this termination flag will be rerun. e.g. termination_flags=’max_number_retries’

  • new_mesa_flag (dict) – Dictionary of flags with their value to add as extra columns to the grid.csv. The user can specify any arbitrary amount of flags. e.g. new_mesa_flag = {‘varcontrol_target’: 0.01}

update_final_values()[source]

Update the final values in the HDF5 file.

class posydon.grids.psygrid.PSyGridIterator(grid)[source]

Bases: object

Class for iterating runs (i.e., PSyRunView instances) in a PSyGrid.

Initialize by pointing to the PSyGrid object.

class posydon.grids.psygrid.PSyRunView(psygrid, run_index)[source]

Bases: object

Access runs in HDF5 grid without opening all data.

Example

mygrid = PSyGrid(“thegrid.h5”) # opens a stored grid myrun = mygrid[0] # get a “view” of the first run in the grid print(mygrid[1].history1.star_age)

t1 = myrun[“binary_history”][“age”] t2 = myrun[“binary_history”].age t3 = myrun.binary_history[“age”] t4 = myrun.binary_history.age

print(mygrid[1].history1.star_age)

Initialize by linking to a PSyGrid object and setting run index.

posydon.grids.psygrid.downsample_history(bh, h1, h2, params)[source]

Downsample history data of a run.

Parameters

  • bh (record array) – The binary history table.

  • h1 (record array) – The history of star 1.

  • h2 (record array) – The history of star 2.

  • params (ConfigFile) – A ConfigFile instance holding the downsampling parameters.

Returns

The three record arrays corresponding to the downsample binary, star 1, and star2 histories.

Return type

tuple of record arrays

posydon.grids.psygrid.downsample_profile(profile, params)[source]

Downsample a profile table.

Parameters

  • profile (record array) – The profile data with column names defined.

  • params (ConfigFile) – A ConfigFile instance holding the downsampling parameters.

Returns

The downsampled profile.

Return type

record array

posydon.grids.psygrid.join_grids(input_paths, output_path, compression='gzip9', description='joined', verbose=True)[source]

Join two or more PSyGrid HDF5 files into one.