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.

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

   docker login registry.gitlab.com
   

3. 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:v0.4.0
   

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

5. EoS data file. Add your Equation of State (EoS) data file to the input folder. QLIMR supports two conventions: MUSES EoS tables or the QLIMR format, in which the first column represents total energy density and the second column represents pressure. The columns should be delimited by a comma (“,”) and the file must be in either .csv or .h5 format. Additionally, the file should be named eos.

6. 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:v0.3.5 python3 qlimr.py --eos_name EoS
   

   The only required flag in the arguments for qlimr.py is --eos_name, which specifies the name of the equation of state provided by the user. For more information about all the input parameter options, please refer to the source code section. To use Sly as a default example EoS, please refer to the example section.

7. Output. Retrieve the output file named observables from the output directory, which is in either .csv or .h5 format according to the user’s specifications.

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 execution section. 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
   

2. 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 2 of the previous subsection.

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

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

   python3 qlimr.py  --eos_name EoS
   

5. Output. Retrieve the output file named observables from the output directory that is already in the repository.

Calculation Engine