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.

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.

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.

  • delta_cp_muon: (number, default: `0.0`, unit: MeV) Fixed difference between muon and electron chemical potentials.

  • delta_cp_tau: (number, default: `0.0`, unit: MeV) Fixed difference between tau and electron chemical potentials.

  • delta_cp_muon_neutrino: (number, default: `0.0`, unit: MeV) Fixed difference between muon neutrino and electron neutrino chemical potentials.

  • delta_cp_tau_neutrino: (number, default: `0.0`, unit: MeV) Fixed difference between tau neutrino and electron neutrino chemical potentials.

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