<commit_before>.. _getting_started

Getting Started 
===============

To wrap a sector model, you need to write a model configuration using yaml
files.

Setup a new system-of-systems modelling project with the following structure::

        /config
        /planning
        /data
        /models

The ``config`` folder contains the configuration for the system-of-systems
model::

        /config/model.yaml
        /config/timesteps.yaml

The ``model.yaml`` file contains the following::

The ``timesteps.yaml`` contains the following::


The ``planning`` folder contains one file for each ::

        /planning/pre-specified.yaml


The ``data`` folder contains a subfolder for each sector model::

        /data/<sector_model_1>
        /data/<sector_mdoel_2>


The ``/data/<sector_model>`` folder contains all the configuration files for a
particular sector model.  See adding a sector model for more information.::

        /data/<sector_model>/inputs.yaml
        /data/<sector_model>/outputs.yaml
        /data/<sector_model>/time_intervals.yaml
        /data/<sector_model>/regions.geojson
        /data/<sector_model>/interventions/
        /data/<sector_model>/assets/

The ``/models/<sector_model/`` contains the executable for a sector model,
as well as a Python file which implements :class:`smif.sector_model.SectorModel`
and provides a way for `smif` to run the model, and access model outputs.
See adding a sector model for more information.::


       /models/<sector_model>/model_wrapper.py
       /models/<sector_model>/<executable or library><commit_msg>Added config file examples to getting started<commit_after>.. _getting_started

Getting Started 
===============

To wrap a sector model, you need to write a model configuration using yaml
files.

Setup a new system-of-systems modelling project with the following structure::

        /config
        /planning
        /data
        /models

The ``config`` folder contains the configuration for the system-of-systems
model::

        /config/model.yaml
        /config/timesteps.yaml

The ``planning`` folder contains one file for each ::

        /planning/pre-specified.yaml

The ``data`` folder contains a subfolder for each sector model::

        /data/<sector_model_1>
        /data/<sector_mdoel_2>

The ``/data/<sector_model>`` folder contains all the configuration files for a
particular sector model.  See adding a sector model for more information.::

        /data/<sector_model>/inputs.yaml
        /data/<sector_model>/outputs.yaml
        /data/<sector_model>/time_intervals.yaml
        /data/<sector_model>/regions.geojson
        /data/<sector_model>/interventions/
        /data/<sector_model>/assets/

The ``/models/<sector_model/`` contains the executable for a sector model,
as well as a Python file which implements :class:`smif.sector_model.SectorModel`
and provides a way for `smif` to run the model, and access model outputs.
See adding a sector model for more information.::

       /models/<sector_model>/run.py
       /models/<sector_model>/<executable or library>

System-of-Systems Model File
----------------------------

The ``model.yaml`` file contains the following::

        sector_models:
        - name: energy_supply
          path: ../../models/energy_supply/run.py
          classname: EnergySupplyWrapper
          config_dir: .
          initial_conditions:
          - initial_conditions.yaml
          interventions:
          - interventions.yaml
        timesteps: timesteps.yaml
        planning:
          pre_specified:
            use: true
            files:
            - pre-specified.yaml # The build instructions
          rule_based:
            use: false
            files: []
          optimisation:
            use: false
            files: []
        assets:
        - assets.yaml


System-of-systems Planning Years
--------------------------------

The ``timesteps.yaml`` contains the following::

        - 2010
        - 2011
        - 2012

This is a list of planning years over which the system of systems model will
run.

Inputs File
-----------

The ``inputs.yaml`` file defines the dependencies of one model upon another.
For example, in energy supply::

        dependencies: 
        - name: electricity_demand
          spatial_resolution: DEFAULT
          temporal_resolution: DEFAULT
          from_model: [energy_demand, transport]
        - name: gas_demand
          spatial_resolution: DEFAULT
          temporal_resolution: DEFAULT
          from_model: energy_demand

The keys ``spatial_resolution`` and ``temporal_resolution`` define the 
resolution at which the data are required.  ``from_model`` defines the model
from which the dependendency is required.

Outputs File
------------

The ``outputs.yaml`` file defines the output metrics from the model.
For example::

        metrics:
          - name: total_cost
          - name: water_demand
          - name: total_emissions

Wrapping a Sector Model
-----------------------

To integrate a sector model into the system-of-systems model, it is necessary
to write a Python wrapper, 
which implements :class:`smif.sector_model.SectorModel`.
{'fraction_non_alphanumeric': 0.10716365754222482, 'fraction_numerical': 0.0031061929722384003, 'mean_word_length': 2.4716981132075473, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3481012', 'n_tokens_mistral': 1441, 'n_tokens_neox': 1338, 'n_words': 464}