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

.. 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 <https://docs.docker.com/get-docker/>`_.
   
   ..

   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:v1.0.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:v1.0.0 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 *Parameters* 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.
      

.. container::

Local Usage
------------

.. container::

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

   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.
          
  
.. container::


Calculation Engine
------------------

To run the QLIMR module on the MUSES Calculation Engine (CE), please refer to the 
`Quick Start Guide <https://musesframework.io/docs/user/quickstart.html>`_ 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.