.. _installation:

Installation
============

The module has two parts: a Fortran core (``nseosfor``) compiled into the
shared library ``libnseos.so``, and a Python wrapper (``nseospy`` /
``interface.py``) that loads it through ``cffi`` and handles the MUSES
input and output.

Fortran core
------------

Dependencies
~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Requirement
     - Purpose
   * - ``gfortran`` (GCC ≥ 11, Fortran 95)
     - Compiles the ``nseosfor`` sources
   * - ``make``
     - Drives the build

On Debian/Ubuntu:

.. code-block:: bash

   apt-get install gfortran make

Building from source
~~~~~~~~~~~~~~~~~~~~~

From the repository root, run the bundled script:

.. code-block:: bash

   bash install.sh

This compiles the sources in ``src/nseosfor/`` and installs the resulting
shared object at ``lib/libnseos.so`` (the location the Python wrapper expects).
Internally the script runs, in ``src/nseosfor/``:

.. code-block:: bash

   make cleanall     # remove previous build artefacts
   make configure    # create the build directory tree
   make              # compile objects and link lib/libnseos.so

The compiler flags used are ``-Jmod -fPIC -ffree-line-length-512`` and the
library is linked with ``gfortran -shared -fPIC`` (see ``src/nseosfor/makefile``).

Python wrapper
--------------

The wrapper requires Python ≥ 3.10 (the Docker image ships 3.11) and the
packages listed in ``src/requirements.txt``:

.. code-block:: bash

   pip install -r src/requirements.txt

Required packages: ``pandas==2.2.3``, ``PyYAML==6.0.2``, ``cffi==1.17.1``,
``openapi-core==0.19.4``.

``nseospy`` locates the shared library at ``lib/libnseos.so`` relative to the
repository root, so no environment variable is needed as long as
``install.sh`` was run from that root.

Running locally
~~~~~~~~~~~~~~~

Once the library is built and the Python dependencies are installed, run the
module from ``src/``:

.. code-block:: bash

   cd src
   python3 validate_config.py && python3 interface.py

See the :ref:`quickstart` for the configuration and output details.

Docker
------

A pre-built image is available on the MUSES GitLab registry. The ``latest``
tag always points to the most recent release:

.. code-block:: bash

   mkdir -p input output          # output/ is not tracked; create it first
   docker pull registry.gitlab.com/nsf-muses/metamodel:latest
   docker run --rm \
       -v "$(pwd)/input:/opt/input" -v "$(pwd)/output:/opt/output" \
       registry.gitlab.com/nsf-muses/metamodel:latest \
       bash -c "python3 validate_config.py && python3 interface.py"

Both mounted directories must exist before the run or the bind mounts fail.
Files written by the container are owned by ``root``; run
``sudo chown -R "$(id -u):$(id -g)" output`` if you later run the module
locally.

To build the image locally from the provided ``Dockerfile`` instead, use the
helper script (it builds ``metamodel:latest``, creates ``input/`` and
``output/`` if needed, and runs the two-step pipeline against them):

.. code-block:: bash

   bash run_docker.sh

or equivalently:

.. code-block:: bash

   mkdir -p input output
   docker build -t metamodel:latest .
   docker run --rm \
       -v "$(pwd)/input:/opt/input" -v "$(pwd)/output:/opt/output" \
       metamodel:latest \
       bash -c "python3 validate_config.py && python3 interface.py"

The Dockerfile installs ``gfortran`` and ``make``, runs ``install.sh`` at build
time, and then removes the ``nseosfor`` sources, keeping only the compiled
``lib/libnseos.so`` and the Python wrapper.