Master configuration file
==================================

The master configuration is JSON file that provides FLUXOS with information and instructions to run a simulation. It contains pairs of variable/command names and values. The variables/commands needed to run a simulation are:

.. list-table:: Variables/Keywords in MASTER file (JSON type)

    *   - Variable/Keyword
        - any useful descriptive information about the project
    *   - ``DEM_FILE``
        - full path to the ESRI ASCII DEM file (``.asc``). Can be generated from GeoTIFF using the Python preprocessing tool (see :doc:`Digital`)
    *   - ``SIM_DATETIME_START``
        - Simulation start datetime
    *   - ``RESTART``
        - Restart option. If ``TRUE``, the model will load the last output file and restart from there.
    *   - ``PRINT_STEP``
        - temporal resolution of the output files (this is not the model timestep as that is defined by the Courant–Friedrichs–Lewy Condition of numerical stability)
    *   - ``ROUGNESS_HEIGHT``
        - average roughness of the terrain measured in height (m), it is used in friction model and water will be retained until this height
    *   - ``METEO_FILE`` (optional)
        - full path to the snowmelt/rainfall timeseries
    *   - ``INFLOW_FILE`` (optional)
        - full pa/rainfall timeseries
    *   - ``EXTERNAL_MODULES`` => ``ADE_TRANSPORT`` => ``STATUS``
        - activate 2D advection-dispersion solver
    *   - ``EXTERNAL_MODULES`` => ``ADE_TRANSPORT`` => ``D_COEF``
        - dispersion coefficient

Triangular Mesh Configuration (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When built with ``USE_TRIMESH``, the following additional variables are available for configuring unstructured triangular mesh simulations:

.. list-table:: Triangular Mesh Variables/Keywords

    *   - ``MESH_TYPE``
        - Mesh type selector: ``"regular"`` (default) or ``"triangular"``
    *   - ``MESH_FILE``
        - Full path to the triangular mesh file (e.g., ``"domain.msh"`` for Gmsh format)
    *   - ``MESH_FORMAT``
        - Mesh file format: ``"gmsh"`` (Gmsh .msh v2.2) or ``"triangle"`` (Triangle .node/.ele)
    *   - ``BOUNDARY_CONDITIONS``
        - JSON object mapping physical group tags to boundary condition types

The JSON file supports C/C++ syntax for comments: single-line comment (``//``) or comment blocks (``/*`` and ``*/``).

Example (Regular Mesh):

.. code-block:: json

    {
        "COMMNET": "Batch_1 - additional tests for paper",
        "DEM_FILE": "Rosa_2m.asc",
        "SIM_DATETIME_START": "2017SEP01 12:15:00",
        "RESTART": false,

        "INFLOW_FILE": {
            "FILENAME": "Flow_forcing.csv",
            "DISCHARGE_LOCATION":{
                "X_COORDINATE": 425894,
                "Y_COORDINATE": 5785553
            }
        },

        "EXTERNAL_MODULES":{
            "ADE_TRANSPORT":{
                "STATUS": true,
                "D_COEF": 0.01
            }
        },
        "METEO_FILE": "Qmelt_synthetic.fluxos",
        "OUTPUT": {
            "OUTPUT_FOLDER": "../fluxos_out",
            "PRINT_STEP": 3600,
            "H_MIN_TO_PRINT": 0.005
        },
        "ROUGNESS_HEIGHT": 0.005

    }

Example (Triangular Mesh):

.. code-block:: json

    {
        "COMMNET": "Triangular mesh simulation",
        "DEM_FILE": "domain_dem.asc",
        "SIM_DATETIME_START": "2017SEP01 12:15:00",
        "RESTART": false,

        "MESH_TYPE": "triangular",
        "MESH_FILE": "domain.msh",
        "MESH_FORMAT": "gmsh",
        "BOUNDARY_CONDITIONS": {
            "1": {"type": "wall"},
            "2": {"type": "outflow"}
        },

        "INFLOW_FILE": {
            "FILENAME": "Flow_forcing.csv",
            "DISCHARGE_LOCATION":{
                "X_COORDINATE": 425894,
                "Y_COORDINATE": 5785553
            }
        },

        "EXTERNAL_MODULES":{
            "ADE_TRANSPORT":{
                "STATUS": true,
                "D_COEF": 0.01
            }
        },
        "METEO_FILE": "Qmelt_synthetic.fluxos",
        "OUTPUT": {
            "OUTPUT_FOLDER": "../fluxos_out",
            "PRINT_STEP": 3600,
            "H_MIN_TO_PRINT": 0.005
        },
        "ROUGNESS_HEIGHT": 0.005
    }

.. note::

   When ``MESH_TYPE`` is set to ``"triangular"``, the DEM file (``DEM_FILE``) is still required. If the ``.msh`` file contains non-zero vertex z-coordinates (generated by the Python preprocessing tool), the solver uses vertex elevations directly -- computing cell bed elevation as the mean of its three vertex z values. Otherwise, the solver falls back to interpolating bed elevation from the DEM grid. The ``MESH_FILE`` provides the mesh topology, while boundary conditions are defined by physical group tags (mapped via ``BOUNDARY_CONDITIONS``).

   **Tip:** Use the Python preprocessing tool to generate both the ``.msh`` file (with embedded DEM elevations) and the ``modset.json`` config. See :doc:`Digital` for details.