Quick Start

This section offers a quick guide for users who want to run QLIMR with minimal instructions. The module can be executed using three different approaches: i) a Docker container, ii) locally on the user’s machine, or iii) through the MUSES Calculation Engine. Below, you will find instructions for running QLIMR with each of these methods.

Docker Container

The easiest way to run QLIMR is through a Docker container. Docker provides a consistent environment for running applications, ensuring QLIMR’s dependencies are met regardless of the host system. To run QLIMR using Docker please follow the steps below.

  1. Installation. Before proceeding, ensure Docker is installed on your local machine. You can find detailed installation instructions on the official Docker documentation website.

  1. Login. Open Docker Desktop and log into the container registry

    docker login registry.gitlab.com
    
  2. Docker Image. First, open Docker Desktop and log into the container registry. Then, you can pull the QLIMR Docker image by executing the following commands in a new terminal

    docker pull registry.gitlab.com/nsf-muses/ns-qlimr/qlimr:v1.1.0
    
  1. Directories setup. Create a directory for your project, including separate folders for inputs and outputs, in your preferred location. Then, navigate into that directory

    mkdir qlimr && mkdir qlimr/input qlimr/output && cd qlimr
    
  1. EoS data file. Place your Equation of State (EoS) data file in the input folder. QLIMR supports two formats:

    1. MUSES format: Follows the column conventions defined by the MUSES collaboration.

    2. QLIMR format: A reduced three-column format, in this order: the total energy density \(\varepsilon\) in \(\text{MeV/fm}^{3}\), the pressure \(p\) in \(\text{MeV/fm}^{3}\), and the baryon number density \(n_{B}\) in \(\text{fm}^{-3}\). All three are required, with no header row. The third column is needed even when the baryon mass is not requested, because the exported profiles \(n(R)\) and \(\mu(R)\) are built from it; a file with only two columns is rejected.

    • For the MUSES format, files must be comma-delimited (.csv) or in HDF5 format (.h5). Name the file either eos.csv or eos.h5, depending on the format.

    • For the QLIMR format, only comma-delimited .csv files are supported. The file must be named eos_validated.csv.

  1. Execution. To execute QLIMR with Docker, use the following command

    docker run --platform linux/amd64 -it --rm --name qlimr \
    -v "${PWD}/input:/opt/input" \
    -v "${PWD}/output:/opt/output" \
    registry.gitlab.com/nsf-muses/ns-qlimr/qlimr:v1.1.0 python3 qlimr.py --eos_name EoS
    

    The only required flag in the arguments for qlimr.py is --eos_name, which is a label for the equation of state provided by the user; the file itself is located by name, as described in the previous step.

    Note that every observable switch defaults to false, so the command above computes only the mass and the radius and leaves the remaining columns of observables.csv as nan. To obtain all of them, add --compute_all 1, or request them individually with --compute_inertia 1, --compute_love 1, --compute_quadrupole 1, --compute_mass_and_radius_correction 1, --compute_baryon_mass 1 and --compute_baryon_mass_correction 1. For more information about all the input parameter options, please refer to the Parameters section. To use Sly as a default example EoS, please refer to the example section.

  1. Output. Retrieve the output file named observables.csv from the output directory; it is always written, and if --output_format h5 was set an observables.h5 copy sits beside it. It holds one row per star. If any of --asymptotic_solutions, --interior_solutions or --exterior_solutions was set, the corresponding asymptotic_solutions, interior_solutions and exterior_solutions files appear in the same directory under the same rule – .csv always, plus an .h5 copy when that format was selected – each holding the radial solutions for every star of the run.

Local Usage

Another option for running QLIMR is on your local machine instead of using a container. To do this, certain libraries and dependencies are required. Ensure that your local machine has a modern version of the g++ GNU compiler installed, along with Python and the following dependencies:

  • numpy, pandas, PyYAML, openapi-core, and muses_porter

  • yaml-cpp and GNU Scientific Library

For more information about these dependencies and installation instructions, please refer to the code structure subsection. Once the dependencies are installed, you can follow the steps below.

  1. Clone. Clone the QLIMR repository by running the following command on a new terminal

    git clone https://gitlab.com/nsf-muses/ns-qlimr/qlimr.git
    
  1. EoS data file. Place your Equation of State (EoS) data file in the existing input folder within the repository. You can follow either of the conventions for the data as mentioned in step 5 of the previous subsection.

  1. Build. Navigate to the source code folder, named src, and build the qlimr executable by running

    cd src/ && make
    

    Note: make sure to check the path where the libraries are installed in the Makefile to ensure everything is configured correctly.

  1. Execution. To execute QLIMR locally, use the following command

    python3 qlimr.py  --eos_name EoS
    
  2. Output. Retrieve the output file named observables from the output directory that is already in the repository.

Calculation Engine

To run the QLIMR module on the MUSES Calculation Engine (CE), please refer to the Quick Start Guide or user manual for detailed instructions and information on how to submit jobs. Users can submit any equation of state (EoS), execute it on the CE, and download the results once the job is complete.