Configuration File

The config.yaml file provides the configuration parameters required to execute the Synthesis module. This file defines various settings for the module, such as the type of synthesis to be performed, input files, and output configurations. Here is a two sample configuration file to compute an EoS with the hyperbolic tangent method:

The following sections provide 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.

  • synthesis_type: (string, default: `’attach’`) Determines the type of synthesis to be performed. Options are:

    • attach: Attach EoS at a specified variable and value.

    • maxwell: Maxwell construction.

    • gibbs: Gibbs construction.

    • hyperbolic-tangent: Interpolated EoS using the hyperbolic tangent method.

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

  • 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

Input File Settings

Defines the input files required by the module. Important: In the CE, it is unnecessary to set up input files, as the CE uses static paths for the files, which are the default paths mentioned below.

  • model1_BetaEq_files: (object) Specifies the input files for the beta-equilibrated nuclear equation of state of the first model:

    • eos_input_file: (string, default: `”eos_beta_model1.csv”`) The beta-equilibrated nuclear EoS data file (CSV format).

    • particle_properties_input_file: (string, default: `”particle_properties_beta_model1.csv”`) The particle properties data file (CSV format).

  • model2_BetaEq_files: (object) Specifies the input files for the beta-equilibrated nuclear equation of state of the second model:

    • eos_input_file: (string, default: `”eos_beta_model2.csv”`) The beta-equilibrated nuclear EoS data file (CSV format).

    • particle_properties_input_file: (string, default: `”particle_properties_beta_model2.csv”`) The particle properties data file (CSV format).

  • model1_Grid_files: (object) Specifies the input files for the gridded nuclear equation of state of the first model. Only required for the Gibbs phase transition:

    • eos_input_file: (string, default: `”eos_grid_model1.csv”`) The gridded nuclear EoS data file (CSV format).

    • particle_properties_input_file: (string, default: `”particle_properties_grid_model1.csv”`) The particle properties data file (CSV format).

  • model2_Grid_files: (object) Specifies the input files for the gridded nuclear equation of state of the second model. Only required for the Gibbs phase transition:

    • eos_input_file: (string, default: `”eos_grid_model2.csv”`) The gridded nuclear EoS data file (CSV format).

    • particle_properties_input_file: (string, default: `”particle_properties_grid_model2.csv”`) The particle properties data file (CSV format).

  • lepton_files: (object) Specifies the input files for the lepton equation of state. Only required for the Gibbs phase transition:

    • eos_input_file: (string, default: `”lepton_eos.csv”`) The lepton EoS data file (CSV format).

    • particle_properties_input_file: (string, default: `”particle_properties_lepton.csv”`) The particle properties data file for leptons (CSV format).

Output File Settings

Controls the output files generated by the module, and are under the output key:

  • output_particle_properties: (boolean, default: `false`) If set to true, the module outputs particle properties data. Requires the relevant input file specified by particle_properties_input_file.

  • output_compOSE: (boolean, default: `false`) If set to true, the module outputs the parameters for creating the compOSE file. Requires the eos_input_files to be specified.

  • output_derivatives: (boolean, default: `false`) If set to true, the module outputs the derivatives of the beta-equilibrated equation of state.

  • output_hdf5: (boolean, default: `false`) If set to true, the module outputs data 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

Interpolation Method Settings

Settings for the hyperbolic-interpolation method used during synthesis, under the interpolation_method key:

  • number_of_points: (integer, default: `150`, minimum: 1) Specifies the number of points calculated in the region obtained by the interpolation method.

  • y_variable: (string, default: `”pressure”`) The variable to interpolate to produce a new EoS. Options: pressure, energy_density, speed_of_sound_squared.

  • x_variable: (string, default: `”baryon_density”`) The variable with respect to which the y_variable will be interpolated. Options: baryon_density, baryon_chemical_potential. The baryon_chemical_potential option is only available for y_variable = pressure.

  • use_thermodynamic_consistency: (boolean, default: `true`) If set to true, the module uses thermodynamic consistency to calculate the interpolated EoS. If false, it interpolates all thermodynamic variables independently.

  • x_variable_midpoint: (number, default: `0.0`) Sets the midpoint of the interpolation region.

  • Gamma: (number, default: `0.0`) Specifies the width of the interpolation region.

Attach Method Settings

Parameters for the attachment method, under the attach_method key:

  • attach_variable: (string, default: `”baryon_chemical_potential”`) The variable used to attach the two EoS. Options include various thermodynamic variables like temperature, baryon_density, energy_density, etc.

  • attach_value: (number, default: `1300.0`) The value of the attach_variable used to attach the two EoS.

compOSE Options

Defines options for generating the compOSE file, under the compOSE_options key:

  • baryon_density_spacing: (string, default: `linear`) Specifies the type of spacing in baryon density. Options: linear, logarithmic.

  • baryon_density_points: (integer, default: `301`) Sets the number of points in baryon density.

  • charge_fraction_spacing: (string, default: `linear`) Specifies the type of spacing in charge fraction. Options: linear, logarithmic.

  • charge_fraction_points: (integer, default: `60`) Sets the 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).