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}\) |
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 |
– |
\(\texttt{--R_start}\) |
Initial radius for integration |
0.0004 |
\(\texttt{--initial_epsilon}\) |
Initial value of central energy density |
200.0 |
\(\texttt{--final_epsilon}\) |
Final value of central energy density |
∞ |
\(\texttt{--resolution_in_NS_M}\) |
Resolution in neutron star mass |
0.05 |
\(\texttt{--single_epsilon}\) |
Single value of central energy density |
700.0 |
\(\texttt{--wb11_c}\) |
Initial value of dragging function |
0.1 |
\(\texttt{--A22_int}\) |
Asymptotic constant at 2nd order |
1.0 |
\(\texttt{--output_format}\) |
Output format |
csv |
\(\texttt{--eps_sequence}\) |
Enable epsilon sequence output |
true |
\(\texttt{--stable_branch}\) |
Enable computation on stable branch |
true |
\(\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_all}\) |
Compute all observables |
false |
\(\texttt{--local_functions}\) |
Enable computation of local functions |
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 200 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_{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}\):This parameter is a constant that appears in the asymptotic analysis around the center of the neutron star for the :math:ell=2 perturbation equations at \(\mathcal{O}(\epsilon^{2})\). It has units of one over length squared; however, the input units are dimensionless, as it is normalized with respect to the characteristic length. In practice, this value is not critically important, as it is primarily used to find the particular solutions of the ODE system for \(h^{(2)}_{2}\) and \(k^{(2)}_{2}\). The default value is set to 1.0.
\(\texttt{--output_format}\): This option allows the user to choose between .csv or .h5 formats for the global quantities, meaning the user will obtain either observables.csv or observables.h5 depending on their preference. These are the formats currently handled by the MUSES collaboration. If not specified, the default value is .csv. For local functions, the format is always .csv at this point.
\(\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_{\star}\) 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_{\star}/R_{\star}\) 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}_{\star}\). 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 first order correction of the TOV mass, equatorial radius, mean radius, and stellar eccentricity which enters at order \(\mathcal{O}(\epsilon^{2})\) in the Hartle-Thorne approximation for the \(\ell=0\) mode. By default, this option is set to false unless specified by the user. Additionally, the corrections are normalized by the square of the angular speed of the neutron star.
\(\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{--local_functions}\): This parameter has two options: 1 (true) or 0 (false). If set to 1, it outputs all local functions from the ODE systems used in the perturbation approach, including TOV solutions and metric functions. It will create one file for each central energy density.
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 (or .h5), depending
on the requested format, with a comma (,) as the delimiter. 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_{\star}\) |
\(\text{km}\) |
3 |
Neutron star mass |
\(M_{\star}\) |
\(M_{\odot}\) |
4 |
Dimenstionless moment of inertia |
\(\bar{I}\) |
\(\text{[-]}\) |
5 |
Dimensionless tidal Love number |
\(\bar{\lambda}\) |
\(\text{[-]}\) |
6 |
Dimensionless quadrupole moment |
\(\bar{Q}\) |
\(\text{[-]}\) |
7 |
Stellar eccentricity |
\(e_{s}/\Omega\) |
\(\text{[s]}\) |
8 |
Equatorial radius correction |
\(\delta R_{\textrm{eq}}/\Omega^{2}\) |
\([\text{km} \, \text{s}^{2}]\) |
9 |
Radius correction |
\(\delta R_{\star}/\Omega^{2}\) |
\([\text{km} \, \text{s}^{2}]\) |
10 |
Mass correction |
\(\delta M_{\star}/\Omega^{2}\) |
\([M_{\odot} \, \text{s}^{2}]\) |
Note that the moment of inertia does not depend on the choice of \(\varpi_{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_{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_{\star}^{2} = (I \Omega_{\textsf{user}})/M_{\star}^{2}\). To obtain the corrections of the mass and the radius of the star for a given angular frequency, then
Local functions
The other type of output available to the user is the local functions. These are always provided in .csv format,
with the filename structured as local_functions_e_#.csv, where ‘#’’ represents the central energy density
value. If an entire sequence is specified, the user will obtain multiple local function files corresponding
to each central energy density, depending on the mass resolution. Below is the description and conventions
for the columns in each local function file.
Column |
Name |
Symbol |
Unit |
|---|---|---|---|
1 |
Radial coordinate |
\(R\) |
\(\text{km}\) |
2 |
Pressure |
\(p(R)\) |
\(\text{MeV/fm}^{3}\) |
3 |
Energy density |
\(\varepsilon(R)\) |
\(\text{MeV/fm}^{3}\) |
4 |
Chemical potential |
\(\mu(R)\) |
\(\text{MeV}\) |
5 |
Baryon number density |
\(n(R)\) |
\(\text{1/fm}^{3}\) |
6 |
Metric function \(\mathcal{O}(1)\) |
\(M(R)\) |
\(M_{\odot}\) |
7 |
Metric function \(\mathcal{O}(1)\) |
\(\nu(R)\) |
\([-]\) |
8 |
Metric function \(\mathcal{O}(\epsilon)\) |
\(\varpi^{(1)}_{1}(R)/\Omega\) |
\([-]\) |
9 |
Tidal function \(\mathcal{O}(\epsilon^{2})\) |
\(y(R)\) |
\([-]\) |
10 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(h^{(2)}_{2}(R)/\Omega^{2}\) |
\(\text{s}^{2}\) |
11 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(k^{(2)}_{2}(R)/\Omega^{2}\) |
\(\text{s}^{2}\) |
12 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(m^{(2)}_{2}(R)/\Omega^{2}\) |
\(M_{\odot} \, \text{s}^{2}\) |
13 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(\xi^{(2)}_{2}(R)/\Omega^{2}\) |
\(\text{km} \, \text{s}^{2}\) |
14 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(m^{(2)}_{0}(R)/\Omega^{2}\) |
\(M_{\odot} \, \text{s}^{2}\) |
15 |
Metric function \(\mathcal{O}(\epsilon^{2})\) |
\(\xi^{(2)}_{0}(R)/\Omega^{2}\) |
\(\text{km} \, \text{s}^{2}\) |
16 |
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,