BptkServer
The BptkServer
class provides a REST-API using the Flask framework.
You will typically start the framework by instantiating the bptk
class within a Jupyer notebook, as follows:
from BPTK_Py.server import BptkServer
from flask_cors import CORS
from model import bptk # assuming your model is in a file called model.py that sets up bptk
# Calling the BptkServer class
application = BptkServer(__name__, bptk)
CORS(application)
if __name__ == "__main__":
application.run()
Assuming you save that code in a file called application.py, you can then start the server fro the command line as follows:
export FLASK_ENV=development
export FLASK_APP=application.py
python -m flask run
The server is now available on port 5000 and you can call the endpoints documented below.
Our Introduction to BPTK repository on GitHub contains an introductory notebook that illustrates how to use the BPTK Rest API.
- class BptkServer(import_name, bptk_factory=None, external_state_adapter=None)
This class provides a Flask-based server that provides a REST-API for running bptk scenarios. The class inherts the properties and methods of Flask and doesn’t expose any further public methods.
- GET /
The root endpoint returns a simple html page for test purposes.
- POST /(instance_uuid)/begin-session
This endpoint starts a session for single step simulation. There can only be one session per instance at a time. Currently only System Dynamics scenarios are supported for both SD DSL and XMILE models.
- POST /(instance_uuid)/end-session
This endpoint ends a session for single step simulation and resets the internal cache.
- GET /(instance_uuid)/flat-session-results
Returns the accumulated results of a session, from the first step to the last step that was run in a flat format.
- POST /(instance_uuid)/keep-alive
This endpoint sets the “last accessed time” of the instance to the current time to prevent the instance from timeing out.
Arguments: None
- POST /(instance_uuid)/run-step
This endpoint advances the relevant scenarios by one timestep and returns the data for that timestep.
- Arguments:
- settings: JSON
Dictionary structure with a key “settings” that contains the settings to apply for that step. These can be constants and points.
- flatResults: boolean
When set to true, a flat version of the results is returned.
- GET /(instance_uuid)/session-results
Returns the accumulated results of a session, from the first step to the last step that was run.
- POST /agents
For an agent-based or hybrid model, this endpoint returns all the agents in the model with their corresponding states and properties.
- PUT /agents
For an agent-based or hybrid model, this endpoint returns all the agents in the model with their corresponding states and properties.
- POST /equations
This endpoint returns all available equations given the name of a scenario manager and of a scenario.
- GET /full-metrics
Returns metrics in JSON format. Following metrics are returned: - Instance count - Creation time und current timestep of each instance
- GET /load-state
Loads all instances using the external state adapter
- GET /metrics
Returns metrics in a prometheus compatible format.
- POST /run
Given a JSON dictionary that defines the relevant simulation scenarios and equations, this endpoint runs those scenarios and returns the data generated by the simulations.
- PUT /run
Given a JSON dictionary that defines the relevant simulation scenarios and equations, this endpoint runs those scenarios and returns the data generated by the simulations.
- GET /save-state
Save all instances with the provided external state adapter.
- GET /scenarios
The endpoint returns all available scenarios for the current simulation.
- POST /start-instance
This endpoint starts a new instance of BPTK on the server side, so that simulations can run in a “private” session. The endpoint returns an instance_id, which is needed to identify the instance in later calls.
- Arguments: timeout (dict,optional)
The timeout period after which the instance is delete if it is not accessed in the meantime. The timer is reset every time the instance is accessed. The timeout dictionary can have the following keys: weeks, days, hours, minutes, seconds, milliseconds, microseconds. Values must be integers.