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: EoS Interpolated using the hyperbolic tangent function.

    • gaussian: EoS Interpolated using a Gaussian function.

    • bump: EoS interpolated with a Bump function.

    • smoothstep: Polynomial interpolation of the EoS.

    • statistical_mixture: Treating each EoS as a fluid to create a thermodynamically stable EoS.

  • 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. Required for the Gibbs phase transition and for the statistical mixture (note the two methods use different grid conventions - see Equation of State):

    • 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. Required for the Gibbs phase transition and for the statistical mixture (note the two methods use different grid conventions - see Equation of State):

    • 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 variable x_bar of the interpolation function.

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

  • exp_power: (number, default: `2.0`) Sets the exponent for the Gaussian-like and Bump function. A value of 2.0 corresponds to a standard Gaussian function.

  • auto_profile_from_bounds: (boolean, default: `false`) If set to true, the module automatically compute the interpolation parameters from the start and enpoints based on epsilon.

  • epsilon: (number, default: `1e-3`) Sets the epsilon parameter for the interpolation function. This parameter is used to control the value of the interpolation function at the endpoints.

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.

Statistical Mixture Method Settings

Parameters for the statistical mixture method, under the statistical_mixture key. In theory, the method can be used for EoS with any number of charges, but we have only implemented the merging procedure for EoS with two variables, i.e. finite temperature EoS with only baryon charge. The two EoS tables are supplied through the eos_input_file options of model1_Grid_files and model2_Grid_files (see the Input File Settings section above); the leptonic EoS is not used.

  • deltaV: (number, default: `2.27e-6`) A pseudo-volume that controls the stiffness of the crossover. Default is tuned by the merging of a holographic model and HRG.

  • Tc: (number, default: `128.0`) Critical temperature set by the user. Default assumes the unit to be MeV.

  • y_bounds: (array, default: `[-30, 30]`) Scan range that ensures the mixing weight is between 0 and 1.

  • n_scan: (number, default: `512`) Number of points to be scanned for solving the mixing weight.

  • grid: (object) Grid settings for the merged EoS. All keys below are ignored when mode is “union” (the default).

    • mode: (string, default: `”union”`) Mode for the grid. “union” means we use the grid that is the union of the sampled (T, muB) points of the two input EoSs. “uniform” means that we set a Cartesian grid with some stepsize and interpolate both EoSs in between.

    • T_min: (number, default: `0`) Minimum temperature for “uniform” mode. If left null, it falls back to the lower bound of the union of the two input domains.

    • T_max: (number, default: `400`) Maximum temperature for “uniform” mode. If left null, it falls back to the upper bound of the union of the two input domains.

    • mu_min: (number, default: `0`) Minimum baryon chemical potential for “uniform” mode. If left null, it falls back to the union of the two input domains.

    • mu_max: (number, default: `1000`) Maximum baryon chemical potential for “uniform” mode. If left null, it falls back to the union of the two input domains.

    • dT: (number, default: `0.0`) Temperature step for “uniform” mode. A value <= 0 disables uniform stepping in temperature; the code then uses NT if given, otherwise the union of the input sample points.

    • dmu: (number, default: `0.0`) Baryon chemical potential step for “uniform” mode. A value <= 0 disables uniform stepping in muB; the code then uses Nmu if given, otherwise the union of the input sample points.

    • NT: (integer, default: `0`) Number of evenly spaced temperature points between T_min and T_max for “uniform” mode, used only when dT <= 0. A value <= 0 falls back to the union of the input sample points.

    • Nmu: (integer, default: `0`) Number of evenly spaced baryon chemical potential points between mu_min and mu_max for “uniform” mode, used only when dmu <= 0. A value <= 0 falls back to the union of the input sample points.

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