Creating models using SBML
===========================

The `SBML <https://sbml.org/>`_ integration into MEmilio works via the ``sbml_to_memilio`` executable. 
Building it requires the installation of `libsbml <https://sbml.org/software/libsbml/>`_. Then the general build command
will produce the executable at ``build/bin/sbml_to_memilio``. 

Building the converter
---------------------------------

To build the executable, the following steps are necessary:

1. Install ``libsbml``. The latest releases are available on `GitHub <https://github.com/sbmlteam/libsbml/releases>`_, advice can be found in the `documentation <https://sbml.org/software/libsbml/libsbml-docs/api/c/>`_. The compilation was tested with version 5.20.2. It might work with other versions, but then it has to be updated in the `CMakeLists.txt <https://github.com/SciCompMod/memilio/blob/main/cpp/thirdparty/CMakeLists.txt#L9>`_.
2. Create the CMake files. At the time of writing, the libsbml package installed with default settings could not be found by CMake. Therefore, you have to hint CMake to the location of the ``sbml-config.cmake``, e.g., by adding the flag ``-Dsbml_DIR=<path to folder containing sbml-config.cmake>`` during the configuration step. Be sure to also have set ``MEMILIO_ENABLE_SBML=ON`` (this is ``OFF`` by default).
3. Build the MEmilio project with the general build command (see the :doc:`documentation <installation>` for details).
4. The files generated by ``sbml_to_memilio`` will only be nicely formatted, if `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_ is installed. It will work also without it, but installing it is recommended.

For more information on the build process, please refer to :doc:`../getting_started`.


Usage
------
Call the executable on a given SBML file as 

.. code:: bash

    ./build/bin/sbml_to_memilio <sbml-file>


.. attention:: 

    You have to call the executable from either ``cpp`` or ``cpp/build`` or ``cpp/build/bin``. Otherwise it will not find
    the ``sbml_model_generation`` folder.

If `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_ is not installed, it will end with an error, but produce
the necessary files nevertheless.


It will produce 

 - a folder with the same name as the SBML file in the ``cpp/sbml_model_generation``-directory.
 - an implementation-file called ``ex_<sbml-file-name>.cpp`` that contains the generated code for the model.
 - the necessary additions to the ``CMakeLists.txt`` file in the ``cpp/sbml_model_generation``-directory.

Now, using the general build command with target ``all`` or ``ex_<sbml-file-name>`` will build an executable for the new model. 
For more information on building memilio, we refer to :doc:`../getting_started`.
 

Changing parameters
----------------------
As some parameters (mainly the duration of simulation) are not part of the SBML file, they are set to generic values in 
the generated example file ``cpp/sbml_model_generation/ex_<sbml-file-name>.cpp``. They can also be changed there.


Limitations
-------------
Be careful about your naming, as some names like, e.g., ``Inf`` are ambiguous.

Not every feature implemented in SBML is also supported by MEmilio.
The following features are the most important not supported features:

    - Events not triggered by time
    - Usage of multiple SBML-compartments
    - Rules (unless they are RateRules)
    - The ``^`` operator for exponentiation in functions. This will produce errors during compilation of the generated code, but can then be changed manually.

As in an SBML file all species have to be given separately, it is unfortunately also not possible to automatically use 
the **Population** in MEmilio to stratify the population into different compartments.

In general: Please check your models after the conversion to ensure that everything is working as expected.

BioModels Database
-------------------

The `BioModels Database <https://www.ebi.ac.uk/biomodels/>`_ contains many models written in SBML, also quite a few models 
for epidemiological contexts. If you created your own SBML file for your model, don't forget to upload it there ;) .