===============
Model execution
===============

``execute_model``
=================

Executes the current model in the session. Depending on the types of objects
specified in the model, it will adjust the execution of the LTM
core applications accordingly.

The return value is the last return code and a list of a dictionary of the
programs, including the input file and output file contents.

Example:

.. code-block:: python

    def open_and_write_model(filename: str):
    session = LtmSession("ikernel", ltm_module_path)

    with session:
        try:
            session.load(filename=filename)
            session.write_model()
            last_rc, results = session.execute_model()

        except Exception as e:
            print(e)

.. note::

    The execution will break if any return code is not 0.

Override LTM core location
--------------------------

It is possible to manually override the location of the LTM core
applications with the optional argument ``ltm_core_path`` to ``LtmSession``.

If ``ltm_core_path`` is set to a directory and it exists, it will prepend
that path onto PATH.

.. code-block:: python

    ltm_core_path = "/opt/ltm/release/bin"
    filename = "/path/to/model.json"

    with LtmSession("override", ltm_core_path=ltm_core_path) as session:
        session.load(filename=filename)
        session.write_model()
        last_rc, results = session.execute_model()

``LtmSession`` will raise an exception if ``ltm_core_path`` is not a folder.

.. _set-execute-callback-label:

``set_execute_callback``
========================

``set_execute_callback`` registers a user-callback that will be invoked
after every LTM core program when the model is executing. The callback takes
2 parameters, a ``dict`` and ``any``.

The dictionary is ``program_results`` and ``any`` is any
userdata the user supplies.

.. code-block:: python

    # Callback is invoked after every LTM core application
    def usercallback(program_info: dict, userdata: any):

        print(userdata)
        print(program_info)

        return True

Register the callback with session.

.. code-block:: python

    # Set the callback
    session.set_execute_callback(usercallback, {"user": "data", "num": 42})


``program_info`` structure:

.. code-block:: text

    {
        'return_code': 0,
        'name': 'arcltm < IMPORT_HISTORICAL_SERIES.FLEX > ./historical.out 2>&1',
        'input_file_contents': 'input file contents',
        'log_file_contents': 'output log file contents'
    }