.. index:: pair: page; Using the Python JSON engine
.. _doxid-python_engine_guide:

Using the Python JSON engine
============================

The :ref:`Python JSON engine <doxid-python_json_engine>` can be used to easily integrate simulators with a Python API. There is a minimal working example with two Python JSON engines exchanging simulation time, located in *examples/tf_exchange* directory. We explain how to run it on :ref:`this page <doxid-running_example_exp_1getting_started_experiment_tf_exchange>`.

In order to create your engine, you can use *examples/tf_exchange/engine_1.py* (listed below) as a reference. Just modify the following methods of the ``Script`` class to suit your needs:

* ``:ref:`initialize() <doxid-namespacepython__json__engine_1a6c79e6ba0653aa9eadb8cff8a0d0588d>``` : executed when the engine is initialized

* ``runLoop(timestep)`` : executed when the engine is requested to advance its simulation (from EngineClient::runLoopStep)

* ``:ref:`shutdown() <doxid-namespacepython__json__engine_1afe4562b75299a7560f51cc982d508677>``` : executed when the engine is requested to shutdown

.. ref-code-block:: cpp

	"""Python Engine 1. Will get current engine time and make it accessible as a datapack"""
	
	from nrp_core.engines.python_json import EngineScript
	
	
	class Script(EngineScript):
	    def :ref:`initialize <doxid-namespacepython__json__engine_1a6c79e6ba0653aa9eadb8cff8a0d0588d>`(self):
	        """Initialize datapack1 with time"""
	        print("Engine 1 is initializing. Registering datapack...")
	        self._registerDataPack("datapack1")
	        self._setDataPack("datapack1", {"time": self._time_ns, "timestep": 0 })
	
	    def runLoop(self, timestep_ns):
	        """Update datapack1 at every timestep"""
	        self._setDataPack("datapack1", {"time": self._time_ns, "timestep": timestep_ns })
	        print("DataPack 1 data is " + :ref:`str <doxid-namespacepython__grpc__engine_1a56206c609843cd6bbb0fd1a3d8b4dc49>`(self._getDataPack("datapack1")))
	
	    def :ref:`shutdown <doxid-namespacepython__json__engine_1afe4562b75299a7560f51cc982d508677>`(self):
	        print("Engine 1 is shutting down")
	
	    def :ref:`reset <doxid-namespacepython__json__engine_1a73c8356ee4133ade577c1ea9772f6ed7>`(self):
	        print("Engine 1 is resetting")

More details about the ``EngineScript`` and other Python JSON engine components can be found :ref:`here <doxid-python_json_engine_1python_json_engine_script>`.