.. _readme:
Simulation Modelling Integration Framework
.. image:: https://github.com/nismod/smif/actions/workflows/test.yml/badge.svg :target: https://github.com/nismod/smif/actions/workflows/test.yml :alt: GitHub Actions build status
.. image:: https://img.shields.io/pypi/v/smif.svg :target: https://pypi.python.org/pypi/smif :alt: PyPI package
.. image:: https://img.shields.io/conda/vn/conda-forge/smif.svg :target: https://anaconda.org/conda-forge/smif :alt: conda-forge package
.. image:: https://zenodo.org/badge/67128476.svg :target: https://zenodo.org/badge/latestdoi/67128476 :alt: Archive
.. image:: https://img.shields.io/badge/JORS-10.5334%2fjors.265-blue.svg :target: https://doi.org/10.5334/jors.265 :alt: Journal of Open Research Software paper
.. image:: https://readthedocs.org/projects/smif/badge/?version=latest :target: https://smif.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
smif is a framework for handling the creation, management and running of system-of-systems models.
A system-of-systems model is a collection of system simulation models that are coupled through dependencies on data produced by each other.
smif provides a user with the ability to
create system-of-systems models
add a simulation model to a library of models
run system-of-systems models
In summary, the framework facilitates the hard coupling of complex systems models into a system-of-systems.
There are number of practical limits imposed by the implementation of smif. These are a result of a conscious design decision that stems from the requirements of coupling the infrastructure system models to create the next generation National Infrastructure System Model (NISMOD2).
The discussion below may help you determine whether smif is an appropriate tool for you.
smif is not a scheduler, but has been designed to make performing system-of-systems analyses with a scheduler easier
Geographical extent is expected to be defined explicitly by a vector geometry
fiona <https://github.com/Toblerity/Fiona>
_Inputs and outputs are exchanged at the ‘planning timestep’ resolution
smif has been designed to support the coupling of bottom-up, engineering simulation models built to simulate the operation of a given infrastructure system
smif is not appropriate for
smif is written in Python (Python>=3.5) and has a number of dependencies.
See requirements.txt
for a full list.
The recommended installation method is to use conda <http://conda.pydata.org/miniconda.html>
_, which handles packages and virtual environments,
along with the conda-forge
channel which has a host of pre-built libraries and packages.
Create a conda environment::
conda create --name smif_env python=3.6
Activate it (run each time you switch projects)::
conda activate smif_env
Add the conda-forge channel, which has smif available::
conda config --add channels conda-forge
Finally install smif
::
conda install smif
smif
with other methodsOnce the dependencies are installed on your system,
a normal installation of smif
can be achieved using pip on the command line::
pip install smif
Versions under development can be installed from github using pip too::
pip install git+http://github.com/nismod/smif
To install from the source code in development mode::
git clone http://github.com/nismod/smif
cd smif
python setup.py develop
smif
optionally depends on fiona <https://github.com/Toblerity/Fiona>
and shapely <https://github.com/Toblerity/Shapely>
, which depend on the GDAL and GEOS libraries. These
add support for reading and writing common spatial file formats and for spatial data
conversions.
If not using conda, on Mac or Linux these can be installed with your OS package manager::
# On debian/Ubuntu:
apt-get install gdal-bin libspatialindex-dev libgeos-dev
# or on Mac
brew install gdal
brew install spatialindex
brew install geos
Then to install the python packages, run::
pip install smif[spatial]
smif
from the command lineFollow the getting started guide <http://smif.readthedocs.io/en/latest/getting_started.html>
_ to help set up the
necessary configuration.
To set up an sample project in the current directory, run::
$ smif setup
To list available model runs::
$ smif list
demo_model_run
...
To start the smif app, a user-interface that helps to display, create and edit a configuration, run::
$ smif app
To run a system-of-systems model run::
$ smif run demo_model_run
...
Model run complete
By default, results will be stored in a results directory, grouped by model run and simulation model.
To see all options and flags::
$ smif --help
usage: smif [-h] [-V] {setup,list,run} ...
Command line tools for smif
positional arguments:
{setup,list,app,run} available commands
setup Setup the project folder
list List available model runs
app Open smif app
run Run a model
optional arguments:
-h, --help show this help message and exit
-V, --version show the current version of smif
If you use smif for research, please cite the software directly:
Here's an example BibTeX entry::
@misc{smif_software,
author = {Will Usher and Tom Russell and Roald Schoenmakers and Craig Robson and Fergus Cooper and Thibault Lestang and Rose Dickinson},
title = {nismod/smif vX.Y.Z},
month = Aug,
year = 2018,
doi = {10.5281/zenodo.1309336},
url = {https://doi.org/10.5281/zenodo.1309336}
}
Please also cite the software description paper:
Here's an example BibTeX entry::
@misc{smif_paper,
author = {Will Usher and Tom Russell},
title = {A Software Framework for the Integration of Infrastructure Simulation Models},
journal = {Journal of Open Research Software},
volume = {7},
number = {16},
pages = {1--5},
month = May,
year = {2019},
doi = {10.5334/jors.265},
url = {https://doi.org/10.5334/jors.265}
}
smif was written and developed at the Environmental Change Institute, University of Oxford <http://www.eci.ox.ac.uk>
within the EPSRC sponsored MISTRAL programme, as part of the
Infrastructure Transition Research Consortium <http://www.itrc.org.uk/>
.