Skip to content

LambdaSim API

Jump to bottom
Marco Bonvini edited this page Mar 27, 2017 · 15 revisions

This document describes the methods that available for APIs created by LambdaSim.

URL structure

LambdaSim uses ApiGateway to create a public API. ApiGateway builds URLs that have the following structure

https://API_ID.execute-api.AWS_REGION.amazonaws.com/prod/FUNCTION_NAME

where

  • API_ID is the ID of the AWS ApiGateway REST API,
  • AWS_REGION is the specifier of the AWS region where the API is deployed,
  • FUNCTION_NAME is the name of lambda function exposed through the REST API.

In the following sections to simplify the notation we'll reference to a generic URL with https://<...>/FUNCTION_NAME.

GET https://<...>/FUNCTION_NAME

LambdaSim builds API for models exported using the Functional Mockup Interface standard FMI. Such models, also known as Functional Mockup Units (FMUs) contain an XML model description file. The API allows to retrieve this file, for example using cURL

curl -X GET https://<...>/FUNCTION_NAME
Code Response type Description
200 application/xml The model description file of the FMU model
404 application/json Error in case of missing file on the server

GET https://<...>/FUNCTION_NAME?config=true

LambdaSim uses a configuration file to specify how to build the API. Examples of such configuration files are available here and here. The API itself provides this configuration file if the boolean query parameter config is equal to true. For example using cURL

curl -X GET https://<...>/FUNCTION_NAME?config=true
Code Response type Description
200 application/json The configuration file used to build the API
404 application/json Error in case of missing file on the server

GET https://<...>/FUNCTION_NAME?dashboard=true

When you build an API with LambdaSim you can define a JSON file that describes the structure of a dashboard for modifying parameters and visualizing simulation results. An example of JSON file definition for a dashboard is this. A GET request to API using the query parameter dashboard=true returns the JSON file dashboard definition, for example using cURL

curl -X GET https://<...>/FUNCTION_NAME?dashboard=true
Code Response type Description
200 application/json The dashboard definition file
404 application/json Error in case of missing file on the server

NOTE: Please note that the dashboard definition file is optional, this means that an API that can correctly perform simulations might not have one.

GET https://<...>/FUNCTION_NAME?readme=true

When you build an API with LambdaSim you can provide a readme file formatted using Markdown. This file generally contains a short description of the model. For example see readme.md. A GET request to API using the query parameter readme=true returns the plain markdown text file, for example using cURL

curl -X GET https://<...>/FUNCTION_NAME?readme=true
Code Response type Description
200 plain/text The content of the readme.md file
404 application/json Error in case of missing file on the server

NOTE: Please note that the readme.md file is optional, this means that an API that can correctly perform simulations might not have one.

POST https://<...>/FUNCTION_NAME

The POST method of the API can be used to perform a simulation and retrieve the results. With a POST you provide to the server the details of the simulation and the server returns the results.

The POST request accepts JSON data that specifies the details of a simulation, for example using cURL you can request to simulate the model from 0 [s] to 10 [s] as

 curl -X POST -d '{"start_time":0,"final_time":10}' https://<...>/FUNCTION_NAME

The following table lists the properties of the JSON data that specify a simulation request

Name Type Required Description
start_time float YES The start time of the simulation in seconds
final_time float YES The end time of the simulation in seconds
options object NO Object that contains options accepted by PyFMI
parameters object NO Object that maps parameter names to their value
input_name string NO Name of the input file to be used

The list of options available via PyFMI are available here.

The following is a list of the default options, please not that you can customize the default options when you deploy your model using LambdaSim.

{
 'CVode_options': {
     'atol': 'Default',
     'discr': 'BDF',
     'external_event_detection': false,
     'iter': 'Newton',
     'rtol': 'Default'
 },
 'Dopri5_options': {
     'atol': 'Default',
     'rtol': 'Default'
 },
 'ExplicitEuler_options': {},
 'ImplicitEuler_options': {},
 'LSODAR_options': {
     'atol': 'Default',
     'rtol': 'Default'
 },
 'Radau5ODE_options': {
     'atol': 'Default',
     'rtol': 'Default'
 },
 'RodasODE_options': {
     'atol': 'Default',
     'rtol': 'Default'
 },
 'RungeKutta34_options': {
     'atol': 'Default',
     'rtol': 'Default'
 },
 'extra_equations': null,
 'filter': null,
 'initialize': true,
 'logging': false,
 'ncp': 0,
 'result_file_name': '',
 'result_handler': null,
 'result_handling': 'file',
 'return_result': true,
 'sensitivities': null,
 'solver': 'CVode',
 'with_jacobian': false,
 'write_scaled_result': false
}

In case of success the API returns a JSON object that contains the names of the model variables and their values during the simulated period. The name of the properties depends on the model and their number can be dynamically selected using the options. The only property that is present in every response is time, that is a list containing the time values on the simulation time grid.

Code Response type Description
200 application/json The results of the simulation
400 application/json Error in case of bad inputs or malformed request
500 application/json Error in case of errors while simulating the model

The following are some examples that show possible errors.

Request with missing final_time

curl -X POST -d '{"start_time":0}' \
https://<...>/FUNCTION_NAME
{
  "code": "400",
  "error_message": "Missing parameter 'final_time'"
}

Request with final_time < start_time

curl -X POST -d '{"start_time":10,"final_time":0}' \
https://<...>/FUNCTION_NAME
{
  "code": "400",
  "error_message": "The parameter 'final_time'=0.0 <= 'start_time'=10.0"
}

Request with wrong parameter name

curl -X POST -d '{"start_time":0, "final_time":86400, "parameters": {"a": 3}}' \
https://<...>/FUNCTION_NAME
{
  "code": "400",
  "error_message": "Error while setting parameter a=3. The variable a could not be found."
}

Request with invalid options

curl -X POST -d '{"start_time":0, "final_time":86400, "options": {"a": 3}}' \
https://<...>/FUNCTION_NAME
{
  "code": "500",
  "error_message": "Internal error while simulating the model: The key: a, is not a valid algorithm option"
}
Clone this wiki locally