2. User Interface

The user interface of Diskpop is the parameters.json file, which stores all of the user-defined parameters to initialise the disc population and customise the type of evolution. The output is printed on an .hdf5 file that can be read with the library popcorn (described in the dedicated section).

2.1. Initial parameters

The default parameters.json is shown below:

{
	"parameters_options": {
			"options.MONTECARLO" : true,
			"options.CORRELATION" : true,
			"options.REPRODUCIBILITY": true,
			"options.MHD": false,
			"options.INTERNAL_PHOTOEV": false,
			"options.DO_PLOTS" : false,
		    "multiprocessing_options" : {
				"parallel_evol" : false,
				"all_available_proc" : true,
				"nproc" : 10
			}
	},
		
	"parameters_population": [
		{
		
			"parameters_general":
				{
					"output_name" : "default",
					"nysos" : 100,
					"analytic" : true,
					"times_snapshot" : [0.001, 0.01, 0.1, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5, 6, 7, 8, 9, 10],
					"alpha" : 1e-3,
					"dust" : false,
					"limit_discmass": 1e-6,
					"d2g" : 0.01,
					"seed" : 1
				},

			"parameters_mhd":
				{
					"leverarm" : 3,
					"omega" : 0
				},
				
				
			"parameters_imf":
				{
					"imf" : "kroupa",
					"mmin" : 5e-2,
					"mmax" : 50
				},
				
			
			"parameters_correlation":
				{
					"beta" : -0.5,

					"mdisc_slope" : 2.1,
					"mdisc_norm" : 1e-2,
					"mdisc_method": "lognormal",

					"mdot_slope" : 1.5,
					"log_mdot_norm" : -8.44,
					"rdisc_method" : "lognormal",

					"beta_mag_norm" : 0,
					"beta_mag_slope" : 0,
					"beta_mag_method" : "lognormal",

					"alpha_DW_norm" : 1e-3,
					"alpha_DW_slope" : 0,
					"alpha_DW_method" : "lognormal",

					"L_x_norm" : 0,
					"L_x_slope" : 0,
					"L_x_method" : "lognormal",

					"mdot_photoev_norm" : 0,
					"mdot_photoev_slope" : 0,
					"mdot_photoev_method" : "lognormal"
				},
				
				
			
			"parameters_nocorrelation":
				{	
					"beta_mag_mean": 22,
					"alpha_DW_mean": 0,
					"mdisc_mean" : 0.003,
					"rdisc_mean" : 10,
					"L_x_mean": 1e30,
					"mdot_photoev_mean": 0
				},
						
								
						
			"parameters_spreads":
				{	
					"mdisc_spread" : 0.5,
					"rdisc_spread" : 0.5,	
					"alpha_spread" : 0.0,
					"alpha_DW_spread" : 0.0,
					"beta_mag_spread": 0,
					"mdot_photoev_spread" : 0,
					"L_x_spread" : 0	
				}
				
				
				
			}
			
			
		],
		
	"parameters_singledisc":
		{			           			
			"mdisc" : 1e-3,               				
			"rdisc_mean" : 50,                    			
			"mstar" : [1, 2, 3],
			"alpha_DW_mean" : 1e-3,
			"beta_mag_mean" : 0           					                   					                      						
		}	
}

The file is structured in nested sub-groups of parameters depending on which type of property of the simulation they control:

parameters_options set the general properties of the simulation (e.g., whether to perform a Monte-Carlo extraction of the population parameters);
parameters_population are set to simulate a whole population of discs;
parameters_singledisc are set to manually determine the disc parameters.

Below is a description of the meaning (and possible choices, where applicable) of all the simulation parameters. The default values of all the simulation parameters are stored in the defaults.py file.

2.1.1. parameters_options

The options can be set to either true (a) or false (b):

Note

Note the syntax: in .json files, the boolean values must be written in lowercase.

options.MONTECARLO sets whether the disc properties are (a) determined from a distribution (to be specified further in the parameters file) or (b) manually set by the user;

options.CORRELATIONS sets whether the disc properties are determined based on the observed correlations with the stellar mass, \(M_{\mathrm{d}} \propto {M_{\star}}^{\lambda_{\mathrm{m}}}\) and \(\dot M \propto {M_{\star}}^{\lambda_{\mathrm{acc}}}\);

Note

It is only meaningful to set options.CORRELATION to True if options.MONTECARLO is also True. This is because options.MONTECARLO puts the strongest requirement on initial conditions: given that it requires each parameter to be set manually, it does not allow to perform a drawing of the parameters themselves (which could actually make use of the provided correlations).

options.REPRODUCIBILITY: sets the reproducibility (a) or lack thereof (b) of the simulation. If true, setting a seed for the random extractions is required;

options.MHD: sets whether the discs are subjected to MHD winds (a) or not (b);

options.INTERNAL_PHOTOEV: sets whether the discs are subjected to internal photoevaporation (a) or not (b);

options.DO_PLOTS: NEED TO REMOVE THIS

multiprocessing_options: contains the parameters to set to evolve the simulation in parallel;

parallel_evol: sets whether to evolve in parallel (a) or not (b);
all_available_proc: sets whether the simulation should take up all of the available processors on the machine (a) or not (b)
nproc: allows to manually set the number of processors to use (has to be an integer number).

2.1.2. parameters_population

Within parameters_population there are 6 additional levels: parameters_general, parameters_mhd, parameters_imf, parameters_correlations, parameters_nocorrelation and parameters_spreads:

parameters_general
These parameters set the general properties of the simulation and must be set regardless of the type of population and disc evolution.
- output_name: sets the .hdf5 output file name. Can be any string, default value is default.
If default, the file name will be assembled combining the key parameters. With options.MONTECARLO = True, it will be set as ‘(no)dust_Montecarl_corr=(true)false_XYZ’ depending on the presence of dust and correlation between the parameters, where XYZ is the date and time of the simulation; with options.MONTECARLO = False, it will be set as ‘(no)dust_alphavalue_mdiscmean_rdiscmean_single_disc_XYZ’ combining the values of the Shakura & Sunyaev (1973) \(\alpha\) parameter, the mean disc mass and the mean disc radius of the simulation.
- nysos: sets the initial number of discs in the population. Default value is \(100\).
- analytic: can be true or false and sets whether to use the analytic solution. If an analytic solution is not available for the chosen combination of parameters, an error message is printed.
- times_snapshot: ages at which the output will be printed, in Myr. Has to be in the form [age1, age2, …].
- alpha: Shakura & Sunyaev (1973) \(\alpha\) parameter
- dust: can be true or false, sets whether to include dust in the simulation.
- limit_discmass: sets the disc mass (in \(M_{\odot}\)) below which the disc is considered dispersed (see disc dispersal). Default value is \(10^{-6}\).
- d2g: the dust-to-gas ratio of the simulation (standard value \(0.01\)).
- seed: can be an integer number or null. If options.REPRODUCIBILITY is set to True, it sets the seed to use in the
random number generators for the simulation to be easily reproduced. If null, the seed is not set.
parameters_mhd
These parameters set the MHD wind parameters as defined by Tabone et al. (2022). The third parameter, \(\alpha_{\rm{DW}}\), is determined from the correlation with the plasma \(beta\) parameter (see REFREFREF).
- leverarm: Tabone et al. (2022) \(\lambda\) parameter. Default value is 3.
- omega: Tabone et al. (2022) \(\omega\) parameter. Default value is 0.25.
Note

Setting the MHD parameters is only meaningful is options.MHD is set to true.
parameters_imf
These parameters determine how the stellar masses of the population of YSOs are extracted, and need to be set for every type of simulation.
- imf: sets the IMF to use to generate the population of YSOs. Possible options are kroupa (which follows the Kroupa (2002) prescription), single (all stars will have \(M_{\star} = 1 M_{\odot}\)) or custom. If custom, the user must provide a file called mstar.txt with the desired stellar masses, in the same folder as the parameters file, that will be used as input to build the population.
Note

If nysos and the lenght of the mstar.txt files differ, the former will be overwritten to match the number of stellar masses provided.
- mmin: minimum stellar mass [\(M_{\odot}\)]. Default is \(5 \times 10^{-2}\). If imf is kroupa, the minimum stellar mass must be smaller than \(8 \times 10^{-2}\).
- mmax: maximum stellar mass [\(M_{\odot}\)]. Default is \(50\). If imf is kroupa, the maximum stellar mass must be bigger than \(1\).
parameters_correlation
These parameters determine the disc properties when options.CORRELATION is set to True.
- beta: slope of the correlation between the disc aspect ratio and the stellar mass, \(H/R \propto {M_{\star}}^{\beta}\). Default is \(-0.5\).
- mdisc_norm: disc mass for a solar-type star (normalisation of the correlation between the disc mass and the stellar mass) [\(M_{\odot}\)]. Default is \(5 \times 10^{-3}\).
- mdisc_slope: slope of the correlation between the disc mass and the stellar mass, \(M_{\mathrm{d}} \propto {M_{\star}}^{\text{mdisc_slope}}\). Default is 2.1. In the release paper Somigliana et al. 2024, this parameter is \(\lambda_{\mathrm{m}, 0}\).
- mdot_slope: slope of the correlation between the accretion rate and the stellar mass, \(\dot M \propto {M_{\star}}^{\text{mdot_slope}}\). Default is 1.5. In the release paper Somigliana et al. 2024, this parameter is \(\lambda_{\mathrm{acc}, 0}\).
- beta_mag_norm: plasma \(\beta\) parameter for a solar-type star. Default is \(6 \times 10^{-4}.\)
- beta_mag_slope: slope of the correlation between the plasma \(\beta\) parameter and the stellar mass, \(\beta \propto {M_{\star}}^{\text{beta_mag_slope}}\).
- L_x_norm: stellar X luminosity for a solar-type star [erg/s] (normalisation of the correlation between the stellar X luminosity and the stellar mass). Default is \(10^{30}\).
- L_x_slope: slope of the correlation between the stellar X luminosity and the stellar mass, \(L_x \propto {M_{\star}}^{\text{L_x_slope}}\)
- mdot_photoev_norm: mass-loss rate due to internal photoevaporation for a solar-type star [\(M_{\odot}/\rm{yr}^{-1}\)] (normalisation of the correlation between the mass-loss rate and the stellar mass). Default is \(6.25 \times 10^{-9}\).
- mdot_photoev_slope: slope of the correlation between the mass-loss rate due to internal photoevaporation and the stellar mass, \(\dot M_{\rm{photoev}} \propto {M_{\star}}^{\text{mdot_photoev_slope}}\).
Note

Setting this set of parameters is only meaningful if both options.MONTECARLO and options.CORRELATION are set to true.
parameters_nocorrelation
These parameters determine the mean values of the disc properties when options.CORRELATION is set to False.
- mdisc_mean: mean disc mass [\(M_{\odot}\)]. Default is \(5 \times 10^{-2}\).
- rdisc_mean: mean disc radius [au]. Default is 10.
- beta_mag_mean: mean plasma \(\beta\) parameter. Default is \(10^6\).
- alpha_DW_mean: mean Tabone et al. (2022) \(\alpha_{\rm{DW}}\) parameter. Default is \(10^{-3}\).
- L_x_mean: mean stellar X luminosity [erg/s]. Default is \(10^{30}\).
- mdot_photoev_mean: mean mass-loss rate due to internal photoevaporation [\(M_{\odot}/\rm{yr}\)]. Default is \(10^{-9}\).
Note

Setting this set of parameters is only meaningful if options.MONTECARLO is set to true and options.CORRELATION is set to false.
parameters_spreads
These parameters determine the spread of the disc parameters, regardless of whether they correlate with the stellar mass or not.
- mdisc_spread: spread of the correlation between the disc mass and the stellar mass [dex]. Default is 0.5.
- rdisc_spread: spread of the correlation between the disc radius and the stellar mass [dex]. Default is 0.5.
- beta_mag_spread: spread of the correlation between the plasma \(\beta\) parameter and the stellar mass [dex]. Default is 0.
- alpha_spread: spread of the correlation between the Shakura & Sunyaev (1973) \(\alpha\) parameter and the stellar mass [dex]. Default is 0.
- L_x_spread: spread of the correlation between the stellar X luminosity and the stellar mass [dex]. Default is 0.1.
- mdot_photoev_spread: spread of the correlation between the mass-loss due to internal photoevaporation and the stellar mass [dex]. Default is 0.5.
Note

Setting this set of parameters is only meaningful if options.MONTECARLO is set to true - otherwise, the parameters are determined from the single disc mode.

2.1.3. parameters_singledisc

mstar: array of stellar masses [\(M_{\odot}\)] in the form [Mstar1, Mstar2, …].
mdisc: array of disc masses [\(M_{\odot}\)] in the form [Mdisc1, Mdisc2, …].
rdisc: array of disc radii [au] in the form [Rdisc1, Rdisc2, …].

Note

Setting this set of parameters is only meaningful if options.MONTECARLO is set to false.

2.2. Running Diskpop

Once the parameter are set in the parameters.json file, this is how to run a Diskpop simulation from terminal:

cd path_to_diskpop_folder
python run_set.py parameters.json

The simulation will print the output file name, determined with the output_name parameter, together with the number of time steps selected. While the simulation proceeds, the current time step is also printed. If a disc ends up being dispersed during the simulation, that information is also printed on screen.

2.3. Output

The output of a Diskpop run in a .hdf5 file named according to the choice of the output_name parameter. In the following, we briefly explain the structure of .hdf5 files for ease of understanding - however, the popcorn library (described here) allows to readily read and analyse the output and takes care of the .hdf5 file.

In this section, we aim at giving some basic ideas on .hdf5 files; for a deeper discussion, we suggest the HDF5 library webpage and the h5py documentation.

The Hierarchical Data Format (HDF) version 5 is a file format that supports heterogeneous and complex data. HDF files are structured ‘directory-like’, allowing to organize the information stored in one single file in a way that is very similar to a computer’s folders system. What is a ‘directory’ or a ‘folder’ in a computer, is a ‘group’ in HDF; what is a ‘file’ in a computer, is a ‘dataset’ in HDF. Groups are folder-like elements in a file that can contain other groups or datasets, while datasets contain the actual data stored in the file as well as metadata describing them.

_images/hdf5_structure.pdf — Structure of a .hdf5 file.

A key feature of .hdf5 files is that they are designed to store big data, and are therefore compressed and easy to slice. Moreover, HDF is a heterogeneous format - meaning that the same file can contain datas of different types, just as much as directories in computers do.

Despite the numerous similarities with directories, HDF files cannot be accessed exactly as a folder on the computer; however, using a programming language, it is possible to access the information stored in the metadata - which are already linked to the group of datasets of interest. For users of Diskpop, this is done within popcorn.

In Diskpop, each simulation returns a .hdf5 file as an output. The first level of groups are represented by the timesteps at which the population was evolved (given in input with the times_snapshot parameter); each of these groups/directories in turn contains other groups, which represent the single YSOs in the population; these groups are then splitted in two further groups, which contain the datasets for the star and disc respectively. popcorn bypasses the need to slice the output file and gives N-dimensional arrays containing the disc and stellar properties for each YSO in the population at all timesteps.