Parameters
This section provides a detailed explanation of the input parameters and output quantities used in the module. Each variable
is described along with its corresponding conventions and units. It is important to note that within the module’s repository,
there is a YAML file located in the /api folder, named OpenAPI_Specifications_QLIMR.yaml. This file contains comprehensive details
on all input and output parameters, including their specifications. It is a useful resource, as it lists the default values, the
data type of each parameter, and their respective ranges. For more information, you can access the full specifications at the
following link: OpenAPI_Specifications
Inputs
This subsection outlines the input conventions for the EoS table that users must provide, as well as the input flag parameters available when using the module.
EOS DATA FILE
Users can offer two types of EoS table conventions. The first is the MUSES EoS table convention, which consists of ten columns detailed as follows, with each column separated by a comma:
Column |
Name |
Symbol |
Unit |
|---|---|---|---|
1 |
Temperature |
\(T\) |
\(\text{MeV}\) |
2 |
Baryon chemical potential |
\(\mu_{B}\) |
\(\text{MeV}\) |
3 |
Strange chemical potential |
\(\mu_{S}\) |
\(\text{MeV}\) |
4 |
Charge chemical potential |
\(\mu_{Q}\) |
\(\text{MeV}\) |
5 |
Baryon number density |
\(n_{B}\) |
\(\text{fm}^{-3}\) |
6 |
Strangenes number density |
\(n_{S}\) |
\(\text{fm}^{-3}\) |
7 |
Charge number density |
\(n_{Q}\) |
\(\text{fm}^{-3}\) |
8 |
Total energy density |
\(\varepsilon\) |
\(\text{MeV/fm}^{3}\) |
9 |
Pressure |
\(p\) |
\(\text{MeV/fm}^{3}\) |
10 |
Entropy |
\(s\) |
\(\text{fm}^{-3}\) |
Files should be named eos and can be in either .csv or .h5 format. Alternatively, users may provide a validated EoS data file named
eos_validated.csv in the following format, with columns also separated by a comma:
Column |
Name |
Symbol |
Unit |
|---|---|---|---|
1 |
Total energy density |
\(\varepsilon\) |
\(\text{MeV/fm}^{3}\) |
2 |
Pressure |
\(p\) |
\(\text{MeV/fm}^{3}\) |
3 |
Baryon number density |
\(n_{B}\) |
\(\text{fm}^{-3}\) |
The third column is required. It is what the baryon mass is computed from, and it also gives the baryon number density and the chemical potential as radial profiles, the latter through the Euler relation at zero temperature, \(\mu = (\varepsilon + p)/n_{B}\). A two-column table is rejected.
The first two columns must increase strictly down the table: the pressure because the physics requires it, and the energy density because it is the abscissa of every interpolation the module builds. The baryon number density is not checked for monotonicity.
INPUT PARAMETERS
The table below summarizes all input parameters, including their descriptions and default values. These parameters are provided by
the user as arguments when running qlimr.py. For more detailed information, please refer to the explanations provided beneath the table.
Flag Parameter |
Description |
Default |
|---|---|---|
\(\texttt{--eos\_name}\) |
Equation of state name |
eos |
\(\texttt{--R\_start}\) |
Initial radius for integration |
0.0004 |
\(\texttt{--single\_epsilon}\) |
Single value of central energy density |
700.0 |
\(\texttt{--initial\_epsilon}\) |
Initial value of central energy density |
250.0 |
\(\texttt{--final\_epsilon}\) |
Final value of central energy density |
inf |
\(\texttt{--wb11\_c}\) |
Initial value of dragging function |
0.1 |
\(\texttt{--A22\_int\_trial\_H}\) |
Trial seed, homogeneous l=2 solve |
1.0 |
\(\texttt{--A22\_int\_trial\_P}\) |
Trial seed, particular l=2 solve |
1.0 |
\(\texttt{--resolution\_in\_NS\_R}\) |
Resolution in neutron star radius |
0.2 |
\(\texttt{--resolution\_in\_NS\_M}\) |
Resolution in neutron star mass |
0.05 |
\(\texttt{--eps\_sequence}\) |
Compute a sequence rather than one star |
true |
\(\texttt{--stable\_branch}\) |
Keep only the stable branch |
true |
\(\texttt{--zero\_stopping\_condition}\) |
Integrate to zero pressure |
true |
\(\texttt{--output\_format}\) |
Output format |
csv |
\(\texttt{--compute\_inertia}\) |
Compute dimensionless inertia |
false |
\(\texttt{--compute\_love}\) |
Compute tidal Love number |
false |
\(\texttt{--compute\_quadrupole}\) |
Compute dimensionless quadrupole |
false |
\(\texttt{--compute\_mass\_and\_radius\_correction}\) |
Compute mass and radius correction |
false |
\(\texttt{--compute\_baryon\_mass}\) |
Compute the background baryon mass |
false |
\(\texttt{--compute\_baryon\_mass\_correction}\) |
Compute the baryon mass correction |
false |
\(\texttt{--compute\_all}\) |
Compute all observables |
false |
\(\texttt{--asymptotic\_solutions}\) |
Export the near-centre expansions |
false |
\(\texttt{--interior\_solutions}\) |
Export the interior radial solutions |
false |
\(\texttt{--exterior\_solutions}\) |
Export the exterior solutions |
false |
\(\texttt{--eos\_name}\): This option allows the user to specify a name for the Equation of State (EoS) used to compute gravitational observables. This information will be stored in the configuration YAML files, enabling users to recall which EoS was employed in their calculations. This flag is required to run the module when executing qlimr.py.
\(\texttt{--R\_start}\): This parameter represents the initial value of the radial coordinate at which the integration of the ODE systems begins. Since all equations diverge exactly at the origin, a very small value—not exactly zero—is chosen for practical numerical integration. The solution from the center up to this selected value can be derived from the asymptotic expansion described in the physics overview section. The units for this parameter are in kilometers (km), and the default value is 0.0004 km.
\(\texttt{--initial\_epsilon}\): If the user wishes to compute a neutron star sequence, this flag specifies the initial value of the central energy density to start the sequence, expressed in units of (MeV/fm³). If not provided, this entry defaults to a value of 250 MeV/fm³. It is important to note that if a smaller value is chosen, the resulting neutron star solutions will yield very large radii with correspondingly low masses.
\(\texttt{--final\_epsilon}\): This parameter specifies the final value of the neutron star sequence, expressed in units of (MeV/fm³). If not provided, the module will use the maximum energy density value from the EoS data file. Thus, by default, this option ensures the exploration of all possible neutron stars based on the given data. This is important because some equations of state (EoS) may exhibit multiple stable branches, which can only be identified by exploring the entire allowed parameter space of central energy densities from the EoS data file.
\(\texttt{--resolution\_in\_NS\_M}\): This option specifies the resolution in the TOV mass for an entire neutron star sequence. The value of this parameter indicates that there will be no difference in mass between adjacent neutron star solutions on the mass-radius (MR) curve that exceeds the specified value. It is measured in solar masses, and the default value is set to 0.05 \(M_{\odot}\).
\(\texttt{--single\_epsilon}\): Each value of central energy density yields a neutron star solution. If the user wishes to compute only one neutron star and its properties, they can provide a single value of central energy density while disabling the neutron star sequence option. The units for this parameter should be given in mega electron-volts per cubic femtometer (MeV/fm³). By default, when eps_sequence is set to false and no value is specified, the parameter takes 700 MeV/fm³.
\(\texttt{--wb11\_c}\): This parameter defines the value of the dragging function at the center of the neutron star (\(\varpi^{(1)}_{1,c}\)). Each chosen value corresponds to a star rotating with a specific angular speed. However, in practice, this value is not critically important, as the outputs are presented in terms of invariant quantities that are normalized with respect to the angular speed \(\Omega\). Generally, this quantity has dimensions of one over time or one over length in geometric units. For this input variable, the units are taken to be dimensionless (neutron star units). For more details, see the appendix on units. The default value is set to 0.1.
\(\texttt{--A22\_int\_trial\_H}\), \(\texttt{--A22\_int\_trial\_P}\): These are the amplitudes the two \(\ell = 2\) solves are seeded with at \(\mathcal{O}(\epsilon^{2})\), the homogeneous one and the particular one respectively. The system is linear, so the seeds are arbitrary: the matching to the exterior at the stellar surface fixes the physical amplitude and divides the trial scale back out. Neither value affects any observable, and the default of 1.0 is as good as any other.
The amplitude that does have meaning, \(A^{(2)}_{2, \mathsf{int}}\), is recovered from the matched solution rather than supplied. It is what the exported near-centre expansions are built from, so that they can be compared with the integrated solution beside them. Earlier versions took a single \(\texttt{--A22\_int}\) as an input, which conflated the arbitrary seed with the physical amplitude.
\(\texttt{--output\_format}\): This option selects the output format, and it is additive rather than
exclusive. The .csv files are always written; selecting .h5 writes an HDF5 copy of each of them alongside,
never in place of them. These are the formats currently handled by the MUSES collaboration. If not
specified, the default value is .csv, and only the .csv files are produced. The rule covers the local
functions as well as the global quantities: every requested solution family is written as .csv, and as
.h5 as well when .h5 is selected. The .csv files are kept unconditionally because the MUSES Calculation
Engine declares the outputs it expects, at fixed paths, before the run: it cannot read the configuration
to decide which file to look for. Writing only the HDF5 file would leave the declared observables
path empty, so a successful run would deliver nothing for the next module of a workflow to consume.
\(\texttt{--eps\_sequence}\): This is an option that accepts only 1 or 0 (or true and false). It indicates whether the user wants to compute an entire neutron star sequence or just a single neutron star solution. If not specified in the arguments, its default value is true, meaning that by default, qlimr.py always runs a neutron star sequence.
\(\texttt{--stable\_branch}\): This parameter has two options: 1 or 0 (true or false). It allows the user to obtain the entire neutron star sequence, including unstable regions (when set to false), or only the stable branch along the mass-radius (MR) curve. If no information is provided by the user, only stable stars within the specified domain will be included in the final output file. The default value is true, meaning that the output file will contain only stable branches.
\(\texttt{--compute\_inertia}\): This parameter has two options: 1 or 0 (true or false). When set to true, in addition to the radius and mass, it computes the dimensionless moment of inertia, given in geometrical units by
where \(M_{*}\) is the TOV mass. By default, this option is set to false.
\(\texttt{--compute\_love}\): This parameter has two options: 1 or 0 (true or false). When activated, it computes the dimensionless tidal Love number \(\bar{\lambda}^{(\text{tid})}\) (also known as tidal deformability), given in geometrical units by
where \(k^{(\text{tid})}_{2}\) is known as the tidal apsidal constant and \(C\) is the \(C \equiv M_{*}/R_{*}\) compactness. By default, this flag parameter is set to false unless activated by the user.
\(\texttt{--compute\_quadrupole}\): This parameter has two options: 1 or 0 (true or false). It is used to compute the dimensionless quadrupole moment deformation of the star due to its rotation. It is defined in geometrical units by
where is the dimensionless spin parameter given by \(\chi \equiv S/M^{2}_{*}\). By default, this option is set to false unless specified by the user.
\(\texttt{--compute\_mass\_and\_radius\_correction}\): This parameter has two options: 1 or 0 (true or false). It is used to compute the second-order rotational corrections to the TOV mass, \(\delta M_{*}\), to the mean radius, \(\delta R_{*}\), and to the equatorial radius, \(\delta R_{\textrm{eq}}\), together with the stellar eccentricity, \(e_{s}\). All of them enter at order \(\mathcal{O}(\epsilon^{2})\) in the Hartle-Thorne approximation, that is, at second order in the spin frequency \(\Omega\). They are often called the first correction, because they are the first correction to the non-rotating term, but the order at which they enter the spin expansion is the second. The mass and the mean radius are \(\ell=0\) results, the mean radius being the monopole deformation averaged over the 2-sphere, \(\delta R_{*} \equiv \xi^{(2)}_{0}(R_{*})\). The shape of the star at the equator also carries the \(\ell=2\) contribution, so \(\delta R_{\textrm{eq}}\) combines \(\xi^{(2)}_{0}\) with \(k^{(2)}_{2}\) and \(\xi^{(2)}_{2}\), and the eccentricity is built from the \(\ell=2\) terms alone. By default, this option is set to false unless specified by the user. The mass and the two radius corrections are normalized by the square of the angular speed of the neutron star; the eccentricity is the square root of an \(\mathcal{O}(\epsilon^{2})\) quantity and therefore scales with the first power of the angular speed, so it is exported as \(e_{s}/\Omega\). The physics overview gives the definitions and the rescaling rules for a star spinning at a chosen frequency.
\(\texttt{--compute\_all}\): This parameter has two options: 1 (true) or 0 (false). When set to 1, it outputs all possible macroscopic observables. The default value is 0.
\(\texttt{--asymptotic\_solutions}\), \(\texttt{--interior\_solutions}\), \(\texttt{--exterior\_solutions}\): The three switches selecting the radial solutions described under Outputs below. Each takes 1 (true) or 0 (false), each is independent of the other two, and each writes a single file for the whole run rather than one per star. Between them they cover the star from the centre outwards: the near-centre series expansions the integration is started from, the integrated solutions of the ODE systems used in the perturbation approach – the TOV background and the metric functions, at the radii they were solved at – and the analytic solutions outside the surface. All three carry the same columns in the same units, so they can be compared directly. Earlier versions wrote one file per central energy density; see Radial solutions for the file names and for why that changed.
\(\texttt{--compute\_baryon\_mass}\): Computes the baryon (rest) mass \(M_{b}\) of the non-rotating background star. This is a single quadrature over a star the TOV solve has already produced, so it costs very little on top of the mass and radius.
\(\texttt{--compute\_baryon\_mass\_correction}\): Computes the rotational correction \(\delta M_{b}/\Omega^{2}\). This is the more expensive of the two: it needs the frame-dragging solution and the \(\ell = 0\) second-order solution underneath it. It does not need the quadrupole, so it is still cheaper than \(\texttt{--compute\_mass\_and\_radius\_correction}\), which additionally requires the quadrupole for the stellar eccentricity.
Setting this implies \(\texttt{--compute\_baryon\_mass}\), since a correction printed beside a
nan background mass would be of no use. The two are separate switches because they cost very
different amounts, and a user who wants only the background mass should not have to pay for the
correction.
\(\texttt{--zero\_stopping\_condition}\): This parameter accepts two values: 1 (true) or 0 (false). If set to 0, the integration stops when the pressure reaches the minimum value provided in the user-supplied EoS table. If set to 1, zero-pressure and zero-energy-density points are appended to the table so that the integration continues until the pressure reaches exactly zero. The default value is 1 (true).
This is the switch that matters for quark matter. A quark star’s energy density does not fall to zero at its surface – it stops at a finite value, around \(4B\) for a bag model – while its pressure does vanish there, as it must with vacuum outside. Such a table should therefore run down to \(p = 0\) and be used with this set to 0, so that its own lowest row is taken as the surface. Setting it to 1 instead prepends a zero-density row and invents a layer the table does not contain.
Outputs
Global quantites
Given a set of input parameters, the module can generate two types of outputs: global quantities and
local functions. The global quantities are saved in a file named observables.csv, with a comma (,)
as the delimiter; when \(\texttt{--output\_format}\) is set to .h5, an observables.h5 copy is
written beside it rather than in its place. The table below outlines the column
conventions used for the global quantities:
Column |
Name |
Symbol |
Unit |
|---|---|---|---|
1 |
Central energy density |
\(\varepsilon_{c}\) |
\(\text{MeV/fm}^{3}\) |
2 |
Neutron star radius |
\(R_{*}\) |
\(\text{km}\) |
3 |
Neutron star mass |
\(M_{*}\) |
\(M_{\odot}\) |
4 |
Baryon mass |
\(M_{b}\) |
\(M_{\odot}\) |
5 |
Dimensionless moment of inertia |
\(\bar{I}\) |
\(\text{[-]}\) |
6 |
Dimensionless tidal Love number |
\(\bar{\lambda}\) |
\(\text{[-]}\) |
7 |
Dimensionless quadrupole moment |
\(\bar{Q}\) |
\(\text{[-]}\) |
8 |
Stellar eccentricity |
\(e_{s}/\Omega\) |
\(\text{[s]}\) |
9 |
Equatorial radius correction |
\(\delta R_{\textrm{eq}}/\Omega^{2}\) |
\([\text{km} \, \text{s}^{2}]\) |
10 |
Mean radius correction |
\(\delta R_{*}/\Omega^{2}\) |
\([\text{km} \, \text{s}^{2}]\) |
11 |
Mass correction |
\(\delta M_{*}/\Omega^{2}\) |
\([M_{\odot} \, \text{s}^{2}]\) |
12 |
Baryon mass correction |
\(\delta M_{b}/\Omega^{2}\) |
\([M_{\odot} \, \text{s}^{2}]\) |
The baryon mass \(M_{b}\) is written when compute_baryon_mass,
compute_baryon_mass_correction or compute_all is set; its rotational
correction is written when compute_baryon_mass_correction or
compute_all is set. Each unrequested quantity is nan, as every
optional column is. \(M_{b}\) is the mass the star’s baryons would have dispersed to
infinity, taking 930.54 MeV per baryon, so \(M_{b} - M_{*}\) is the
gravitational binding energy. For an equation of state whose energy per baryon
at zero pressure exceeds that value – some quark matter does – the difference
is negative, correctly: dispersing such matter to iron would release energy
rather than cost it.
Note that these two columns are inserted, each beside its gravitational
counterpart, rather than appended. Anything reading observables.csv by
column position needs updating for v1.1.0; anything reading it by name does
not.
Note that the moment of inertia does not depend on the choice of \(\varpi^{(1)}_{1,c}\), which yields different values of the neutron star angular speed. This is because the star’s deformation enters at second order in the Hartle-Thorne approximation, making the moment of inertia insensitive to the choice of \(\varpi^{(1)}_{1,c}\). However, this is not the case for the quadrupole moment and the corrections to mass and radius. The deformation of the star due to its rotation dependends on its rotational speed. To compute the quadrupole deformation of a star for a specific angular speed, the user can perform the following operation in geometrical units,
where \(\chi_{\textsf{user}} \equiv S_{\textsf{user}}/M_{*}^{2} = (I \Omega_{\textsf{user}})/M_{*}^{2}\). To obtain the corrections of the mass and the radius of the star for a given angular frequency, then
Radial solutions
The other type of output is the radial solutions: every quantity as a function of depth inside the star, rather than one number per star.
Three files are available, each requested by its own switch and each written to a fixed path:
asymptotic_solutions.csv– the near-centre series expansions the integration is started from, from \(R_{\textrm{start}}\) to \(0.5\,R_{*}\).interior_solutions.csv– the solutions the module integrates, from \(R_{\textrm{start}}\) out to the stellar surface \(R_{*}\), at exactly the radii the equations were solved at.exterior_solutions.csv– the analytic solutions outside the star, from \(R_{*}\) to \(2\,R_{*}\).
All three carry the same columns in the same order and the same units, so one
reader serves them all and they can be compared directly: where the series stops
following the integrated solution is where the expansion has ceased to be valid,
and the interior and exterior meeting at the surface is what the matching
constants are chosen to achieve. A quantity with no meaning in a given region is
written as nan rather than zero – outside the star the fluid displacements
and the tidal variable are not small, they are undefined.
Prior versions wrote one file per star, named local_functions_e_#.csv after
the central energy density. Those names depended on which stars a run happened to
compute, so they could never be declared in advance, and a user requesting them
through the Calculation Engine received nothing at all. There is now a single
file per family at a fixed path, with the central energy density as the first
column, matching observables.csv: one row per star there, one row per radial
point here. Group by the first column to recover the per-star split, rather than
assuming a fixed number of rows per star – the rows follow each star’s own
integration grid.
Below is the description and conventions for the columns, common to all three files.
Column |
Name |
Symbol |
Unit |
|---|---|---|---|
1 |
Central energy density |
\(\varepsilon_{c}\) |
\(\text{MeV/fm}^{3}\) |
2 |
Radial coordinate |
\(R\) |
\(\text{km}\) |
3 |
Pressure |
\(p(R)\) |
\(\text{MeV/fm}^{3}\) |
4 |
Energy density |
\(\varepsilon(R)\) |
\(\text{MeV/fm}^{3}\) |
5 |
Chemical potential |
\(\mu(R)\) |
\(\text{MeV}\) |
6 |
Baryon number density |
\(n(R)\) |
\(\text{1/fm}^{3}\) |
7 |
Metric function \(\mathcal{O}(1)\) |
\(M(R)\) |
\(M_{\odot}\) |
8 |
Metric function \(\mathcal{O}(1)\) |
\(\nu(R)\) |
\([-]\) |
9 |
Metric function \(\mathcal{O}(\epsilon)\) |
\(\varpi^{(1)}_{1}(R)/\Omega\) |
\([-]\) |
10 |
Tidal function \(\mathcal{O}(\epsilon^{2})\) |
\(y(R)\) |
\([-]\) |
11 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(h^{(2)}_{2}(R)/\Omega^{2}\) |
\(\text{s}^{2}\) |
12 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(k^{(2)}_{2}(R)/\Omega^{2}\) |
\(\text{s}^{2}\) |
13 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(m^{(2)}_{2}(R)/\Omega^{2}\) |
\(M_{\odot} \, \text{s}^{2}\) |
14 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(\xi^{(2)}_{2}(R)/\Omega^{2}\) |
\(\text{km} \, \text{s}^{2}\) |
15 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(m^{(2)}_{0}(R)/\Omega^{2}\) |
\(M_{\odot} \, \text{s}^{2}\) |
16 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(\xi^{(2)}_{0}(R)/\Omega^{2}\) |
\(\text{km} \, \text{s}^{2}\) |
17 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(h^{(2)}_{0}(R)/\Omega^{2}\) |
\(\text{s}^{2}\) |
Similarly, the user can multiply by the corresponding desired angular speed of the star to obtain the local functions for that specific rotational configuration. For example,