Configuration File ================== The `config.yaml` file provides the configuration parameters for the Lepton module. It defines various parameters and settings that control the module's functionality, such as which particles to include, the input and output files, and specific options for the calculations. Here is a sample configuration file to compute beta-equilibrium. .. code-block:: yaml global: use_beta_equilibrium: true verbose: 2 check_eos_stability: true particles: use_electron: true use_muon: false output: output_compOSE: true output_derivatives: true output_hdf5: false input: eos_input_file: "nuclear_grid.csv" In the following sections we give an overview of all the parameters available in the configuration file. Global Settings --------------- These parameters define the general settings and options for the module, and are under the **global** key: - **run_name**: *(string, default: "")* Sets a name for the module run. This name will be used to create a subdirectory under `/output/` where the output files will be stored. **Important**: When using Lepton in a workflow in the MUSES Calculation Engine (CE), do not setup a run_name. The CE uses static paths for the files, and setting a run_name will cause the CE to fail. - **use_beta_equilibrium**: *(boolean, default: `false`)* Enables the calculation of the beta-equilibrated equation of state. Requires the input of a nuclear equation of state file specified by `eos_input_file`. - **use_charge_neutrality**: *(boolean, default: `false`)* Enables the calculation of the charge-neutrality equation of state. Requires the input of a nuclear equation of state file specified by `eos_input_file`. - **use_lepton_eos**: *(boolean, default: `false`)* Enables the calculation of a purely leptonic equation of state. The particles included in the calculation must be specified using the options `use_electron`, `use_muon`, `use_tau`, `use_electron_neutrino`, `use_muon_neutrino`, and `use_tau_neutrino`. - **lepton_fraction**: *(number, default: `0.0`, range: 0.0 to 1.0)* Sets the lepton fraction, used only when neutrinos are included in the calculation. - **verbose**: *(integer, default: `0`, range: 0 to 4)* Controls the verbosity level of the output: - `0`: No output - `1`: Minimal output - `2`: Standard output - `3`: Extended output - `4`: Debug output - **check_eos_stability**: *(boolean, default: `false`)* Enables a stability check for the nuclear equation of state, checking if pressure and chemical potential are not decreasing functions of baryon density, and if speed of sound is casual. The results are printed in the `info.yaml` file. Particle Settings ----------------- These parameters specify which leptons and neutrinos are included in the calculations, and are under the **particles** key: - **use_electron**: *(boolean, default: `true`)* Includes electrons in the calculations. - **use_muon**: *(boolean, default: `false`)* Includes muons in the calculations. - **use_tau**: *(boolean, default: `false`)* Includes taus in the calculations. - **use_electron_neutrino**: *(boolean, default: `false`)* Includes electron neutrinos in the calculations. The `lepton_fraction` must be set between 0 and 1. - **use_muon_neutrino**: *(boolean, default: `false`)* Includes muon neutrinos in the calculations. The `lepton_fraction` must be set between 0 and 1. - **use_tau_neutrino**: *(boolean, default: `false`)* Includes tau neutrinos in the calculations. The `lepton_fraction` must be set between 0 and 1. - **use_extra_particles**: *(boolean, default: `false`)* Enables the use of additional particles in the calculations. The additional particles must be specified in the `particles.dat` input file. Input File Settings ------------------- Defines the input files required by the module, and are under the **input** key. **Important**: In the CE, it is not necessary to setup the input files, as the CE uses static paths for the files, which are the default paths below. - **eos_input_file**: *(string, default: `"nuclear_grid.csv"`)* Specifies the nuclear equation of state file in CSV format, located in the `input/` directory. - **particle_properties_input_file**: *(string, default: `"particle_properties.csv"`)* Specifies the file containing particle properties, located in the `input/` directory. - **flavor_equilibration_input_file**: *(string, default: `"flavor_equilibrium.csv"`)* Specifies the file containing nuclear parameters for the flavor equilibration module, located in the `input/` directory. Output File Settings -------------------- Controls the output files generated by the module, and are under the **output** key: - **output_particle_properties**: *(boolean, default: `false`)* Provides a particle properties data output. Requires an input file specified by `particle_properties_input_file`. - **output_flavor_equilibration**: *(boolean, default: `false`)* Provides the flavor equilibration module input. It requires an input file specified by `flavor_equilibration_input_file`, and it will only be generated if `use_charge_neutrality` is enabled. - **output_compOSE**: *(boolean, default: `false`)* Provides an output in compOSE format. Requires the `eos_input_file` to be specified. - **output_derivatives**: *(boolean, default: `false`)* Enables the output of derivatives of the beta-equilibrated equation of state. - **output_hdf5**: *(boolean, default: `false`)* Enables the output of the EoS and the derivatives in HDF5 format, in addition to CSV. Derivatives Settings -------------------- Parameters for controlling numerical derivatives, under the **derivatives** key: - **method** *(string, default: 'gsl')*: Specifies the method to calculate derivatives. Options: - `'gsl'`: Uses the GNU Scientific Library for derivative calculations. - `'finite_difference'`: Uses a finite difference approach with custom settings. - **finite_difference** *(object)*: Controls settings specific to the finite difference method. - **step_type** *(string, default: 'relative')*: Defines how the step size is determined: - `'relative'`: The step size is proportional to the value being differentiated. - `'absolute'`: The step size is fixed. - **step_size** *(number, default: 5.e-3, range: 0.0 to 1.0)*: Sets the magnitude of the step size for derivatives, interpreted based on `step_type`. - **precision** *(integer, default: 1, range: 1 to 3)*: Specifies the order of accuracy for the finite difference method: - 1: First order - 2: Second order - 3: Third order Multidimensional Interpolator Settings -------------------------------------- Parameters for using multidimensional interpolation, under the **multidimensional_interpolator** key: - **use_multidimensional_interpolator**: *(boolean, default: `false`)* Enables multidimensional interpolation for the nuclear equation of state. It must be enabled if your grid is not irregular in both baryon density and baryon chemical potential. - **number_of_points**: *(integer, default: `100`, minimum: 1)* Sets the number of points in density for the multidimensional interpolator. Lepton EoS Parameters --------------------- Defines parameters for the lepton equation of state, under the **lepton_eos_parameters** key: - **electron_cp_initial**: *(number, default: `0.0`, unit: MeV)* Initial electron chemical potential. - **electron_cp_final**: *(number, default: `0.0`, unit: MeV)* Final electron chemical potential. - **electron_cp_step**: *(number, default: `0.0`, unit: MeV)* Step size for electron chemical potential. - **electron_neutrino_cp_initial**: *(number, default: `0.0`, unit: MeV)* Initial electron neutrino chemical potential. - **electron_neutrino_cp_final**: *(number, default: `0.0`, unit: MeV)* Final electron neutrino chemical potential. - **electron_neutrino_cp_step**: *(number, default: `0.0`, unit: MeV)* Step size for electron neutrino chemical potential. compOSE Options --------------- Defines options for generating the compOSE file, under the **compOSE_options** key: - **baryon_density_spacing**: *(string, default: `linear`)* Sets the type of spacing in baryon density. Options: `linear`, `logarithmic`. - **baryon_density_points**: *(integer, default: `301`)* Number of points in the baryon density. - **charge_fraction_spacing**: *(string, default: `linear`)* Sets the type of spacing in charge fraction. Options: `linear`, `logarithmic`. - **charge_fraction_points**: *(integer, default: `60`)* Number of points in the charge fraction. Solver Parameters ----------------- The **solver** section in the `config.yaml` file defines parameters for configuring the non-linear least squares solver options in [Ceres Solver](http://ceres-solver.org/). It specifies the optimization method, linear solver type, and various tolerances to control convergence behavior. - **parameter_tolerance** *(number, default: `1.e-10`, range: 0.0 to 1.0)* Sets the tolerance for parameter updates. Smaller values lead to stricter convergence criteria. - **function_tolerance** *(number, default: `1.e-10`, range: 0.0 to 1.0)* Sets the tolerance for changes in the cost function. Optimization stops when the relative change in the cost function between iterations is less than this value. - **gradient_tolerance** *(number, default: `1.e-12`, range: 0.0 to 1.0)* Sets the tolerance for the gradient norm. When the gradient norm falls below this value, the optimization terminates, assuming a local minimum has been reached. - **use_nonmonotonic_steps** *(boolean, default: `true`)* Enables the use of non-monotonic steps in the solver, allowing temporary increases in the cost function to escape local minima. - **max_num_iterations** *(integer, default: `1000`, minimum: `1`)* Sets the maximum number of iterations for the solver. Larger values allow more steps to refine the solution but may increase computation time. - **method** *(string, default: `'levenbergMarquardt'`)* Specifies the optimization method to solve the system of equations. Available options include: - `'levenbergMarquardt'`: Trust region strategy using Levenberg-Marquardt. - `'dogleg'`: Trust region strategy using Dogleg. - `'bfgs'`: Line search strategy using BFGS. - `'steepestDescent'`: Line search strategy using steepest descent. - `'lbfgs'`: Trust region strategy using L-BFGS. - `'nonlinearConjugateGradient'`: Line search strategy using nonlinear conjugate gradient. - **linear_solver** *(string, default: `'denseQR'`)* Specifies the linear solver type to be used with the selected optimization method. Options include: - `'denseQR'`: Dense QR decomposition. - `'sparseSchur'`: Sparse Schur complement (efficient for large-scale problems). - `'denseNormalCholesky'`: Dense normal Cholesky decomposition. - `'iterativeSchur'`: Iterative Schur complement solver. - **convergence_threshold** *(number, default: `1.e-7`, range: 0.0 to 1.0)* Defines a residual threshold for convergence. Solutions with residuals larger than this value are considered unusable. **Note**: Certain methods and linear solvers may not be compatible. Refer to the [Ceres documentation](http://ceres-solver.org/nnls_solving.html).