AnyLogic Cloud API 8.5.0 Documentation · 2020. 9. 4. · AnyLogic Cloud keeps the inputs and outputs of all the experiments that have been ever run with each model version. Model

AnyLogic Cloud API 8.5.0 Documentation

1 OverviewIn addition to the standard web UI, Anylogic Cloud offers multiple APIs that you can use toconfigure and run simulations programmatically within your analytical workflows, queryexperiment results, build fully customized web interfaces for your models, and do a lot of otherthings. There are four APIs:

RESTful HTTP APIJavaScript APIJava APIPython API

Related resources:

JavaScript API 8.5.0 clientThis documentation in PDF

1.1 Simple YouTube-style embedding of simulationanimationsBefore we dive into AnyLogic Cloud API, we would like to make sure you know that there is asimple way of embedding Cloud-based animations into any web pages without using anyAPI/coding whatsoever.

https://cloud.anylogic.com/files/api-8.5.0/clients/js-client-8.5.0.ziphttps://cloud.anylogic.com/files/api-8.5.0/docs/AnyLogic+Cloud+API+8.5.0+Documentation.pdf

If you want your HTML page to have only the AnyLogic Cloud model animation, you can embedit just like a YouTube video:

A. Locate the tile of the required model (either on the title screen or model screen)B. Click the icon at the bottom right corner of the model tileC. Copy the HTML fragment displayed in the dialog boxD. Paste the fragment into your HTML page where you want the animation to appear:

…

… …

That simple embedding is subject to the following restrictions:

Only animations of public models can be embedded that wayThe animation always refers to the same simulation as the public page of the model, i.e.

to a simulation experiment of the latest model versionIf the latest version has no simulation experiments, an error will occur

Please keep in mind:You will be able to control the model execution only from the default animationtoolbarYou will not be able to change parameters before simulation or save outputsafterwardsWhen you click Stop, the animation will return to the start page

1.2 Authentication with API key and securityconsiderationsAny usage of AnyLogic Cloud API is done on behalf of a particular user. Authentication is donewith the help of the API Key (randomly generated personal identifier). Below you can see anexample of an API Key:

"e05a6efa-ea5f-4adf-b090-ae0ca7d16c20"

The API key is available for subscribers and the Private Cloud users (every Private Cloud userhas their own API key).

To obtain the API key:

A. Log in to AnyLogic Cloud.B. Open your user profile.C. Expand the API section — you will find your key there:

Keep the key safe! If it gets unintentionally exposed, generate a new key and update yourcode with it!

Note, that the API key used in the JavaScript code of your custom web page (that is madepublic or open to an end user or a client) is exposed to whoever can access this web page,since the JavaScript code can be viewed in the browser console. This means that potentially,that person will be able to use the AnyLogic Cloud API under the same account!

Therefore, to protect your account, you should:

Create a separate AnyLogic Cloud account for the required user(s). (If you are using the publicCloud, that account should also be a subscriber account.)

Generate the API key from that user's accountUse that key in the JavaScript codeShare the required model(s) between your account (developer) and the user's account

This way you will have full control of the shared models and the ability to delete the useraccount(s) any time without affecting the models.

2 RESTful HTTP APIThe AnyLogic Cloud API is versioned. The root address contains the version number, e.g. theroot address for API version 8.5.0 for AnyLogic Cloud subscribers:https://cloud.anylogic.com/api/open/8.5.0. The same applies to Private Cloud. The address inthis case will be: /api/open/8.5.0.

2.1 End pointsPlease note that you should provide "Authorization: " header in every HTTP request

https://cloud.anylogic.com/api/open/8.5.0

(see API Key). In AnyLogic HTTP API requests have no parameters. Some requests shouldprovide data objects in the request body. The data objects are described in the next section.

GET /models - returns the array of all Models of the user (the API key owner), i.e. the modelswhere the user has either developer or user access rights.

GET /models/ - returns the Model with the given id.

GET /models/name/ - returns the Model with the given name.

GET /models//versions/number/ - returns the Version with thegiven number (version numbering starts with 1).

GET /models//versions/ - returns the Version with the given id.

GET /versions//experiments returns the array of Experiments created for thegiven model version.

POST /versions//runs, body: Run Request - requests to perform a simulationrun with the inputs contained in the Run Request. This will result in a real new simulationonly if such run has not been performed yet. Returns Experiment Run, but does not wait forsimulation to complete and therefore does not return the outputs.

POST /versions//runs/stop, body: Run Request - stops execution of the modelrun provided in the request body. Does not return anything.

POST /versions//run, body: Run Request - returns Experiment Run containingthe status of the run. The intended use is to query the run state.

POST /versions//results/, body: blank Outputs - returns the Outputsof the completed run with the given id according to the provided outputs template (so thatyou can control which data you will receive). If the run has not been completed, returns404.

POST /versions//results, body: Experiment Result Request - the Outputs of acompleted run with a given id according to the outputs template provided. In contrast tothe previous end point, this one does not require .

GET /versions//runs//progress - returns Experiment Run Statecontaining the status and details of the run (which may be already completed or not).

POST /versions//runs/animation, body: Run Request - starts animated run ofthe model. Waits for the animation to start, and returns Animation SVG Run Info containing,among other things, the host address of the node where the animated run has beencreated.

There are more end points for communication with the animated run (speed changing,pausing, etc.) but we are not describing them here because they only make sense in thebrowser environment (see the corresponding JavaScript API).

2.2 Data objectsThe data structure of AnyLogic Cloud is roughly represented on the picture below. Using theAPI Key obtained from the page of a user, you can access the models listed in that user's MyModels page. Each Model can have multiple versions, and the Version is what you can performexperiments with. AnyLogic Cloud keeps the inputs and outputs of all the experiments thathave been ever run with each model version.

ModelModel is a simple object with a unique id, name, description, array of version ids, and apublic/not public flag:

{ id: "f7771cd8-8d55-486a-b255-10459a349093", name: "Flocks of Boids", description: "Original Boids, developed by Craig Reynolds, is an artificial life program ", modelVersions: [ "7c702819-b413-417b-aa61-60becd029e3c", "de699d41-1f0c-497d-b544-413685f82d2b", "b845d4f9-972c-45c7-ae6a-7a762ab81c03" ], published: false}

VersionVersion contains full information about the model inputs, outputs, and dashboardconfiguration in its experimentTemplate field, for example:

{ id: "def089c4-96a3-40f2-aefb-de1af471fe2f", version: 6, experimentTemplate: { inputs: [ {name: "{STOP_MODE}", type: "STRING", units: null, value: "STOP_MODE_AT_TIME"}, {name: "{START_TIME}", type: "DOUBLE", units: "SECOND", value: "0"}, {name: "{STOP_TIME}", type: "DOUBLE", units: "SECOND", value: "1000000"}, {name: "{START_DATE}", type: "DATE_TIME", units: null, value: "2019-05-15T00:00"}, {name: "{STOP_DATE}", type: "DATE_TIME", units: null, value: "2019-05-26T13:46:40"}, {name: "{MAX_MEMORY_MB}", type: "INTEGER", units: null, value: "512"}, {name: "Arrival rate", type: "DOUBLE", units: null, value: "1"}, {name: "Mean service time", type: "DOUBLE", units: null, value: "2"}, {name: "Server capacity", type: "INTEGER", units: null, value: "3"}, {name: "Check failure probability", type: "DOUBLE", units: null, value: "0.2"} ], outputs: [ {name: "Queue size stats", type: "STATISTICS_CONTINUOUS", units: null, value: null}, {name: "Total time in system|Total time in system", type: "HISTOGRAM_DATA", units: null, value: null}, {name: "Utilization|Server utilization", type: "DOUBLE", units: null, value: null}, {name: "Mean queue size|Mean queue size", type: "DOUBLE", units: null, value: null} ], dashboard: { }

}}

Please note that the inputs array contains the system inputs of the model (the ones in curlybraces) such as the {STOP_TIME} or {MAX_MEMORY_MB} as well as the user-defined inputs. Thevalue field contains the default value of the input and is always a string regardless of the inputtype. The outputs part of the object is not the actual outputs of some simulation run (those aredescribed in the Outputs section), but a list of outputs that are available for that particularmodel version, therefore the value field is always null.

The dashboard configuration is irrelevant from the API user viewpoint, so we will skip itsstructure.

ExperimentExperiment contains the input settings of an experiment saved in the AnyLogic Cloud UI. It canbe used (e.g. to set the inputs of a run invoked via the AnyLogic Cloud API) by calling thefunction createInputsFromExperiment() of the CloudClient object. It has the followingstructure:

{ uuid: "f3f441f3-8117-4423-9b1c-75b4680c715b", modelVersion: "def089c4-96a3-40f2-aefb-de1af471fe2f", name: "Server Capacity Variation", type: "PARAMETER_VARIATION", inputs: [ {name: "Arrival rate", type: "DOUBLE", units: null, value: "1"}, {name: "Check failure probability", type: "DOUBLE", units: null, value: "0.2"}, {name: "Mean service time", type: "DOUBLE", units: null, value: "2"}, {name: "Server capacity", type: "FIXED_RANGE_INTEGER", units: null, value: "{"min":3,"max":7,"step":1}"}, {name: "{MAX_MEMORY_MB}", type: "INTEGER", units: null, value: "512"}, {name: "{RANDOM_SEED}", type: "LONG", units: null, value: "1"}, {name: "{START_DATE}", type: "DATE_TIME", units: null, value: "2019-05-15T00:00"}, {name: "{START_TIME}", type: "DOUBLE", units: "SECOND", value: "0"}, {name: "{STOP_DATE}", type: "DATE_TIME", units: null, value: "2019-05-26T13:46:40"}, {name: "{STOP_MODE}", type: "STRING", units: null, value: "STOP_MODE_AT_TIME"}, {name: "{STOP_TIME}", type: "DOUBLE", units: "SECOND", value: "1000000"} ]}

Note that the value field of an input item always contains a string, for example, for the input ofrange type ("FIXED_RANGE_INTEGER") it is a string with unparsed JSON with min, max, and stepfields.

Possible values of the type field are listed in Input types section. The unit field can containnull or one of the values listed in the Units section.

OutputsThe Outputs object is fairly complex and we strongly recommend using the Cloud clientsprovided by AnyLogic, since they contain methods simplifying navigation through Outputs(such methods are present in e.g. SingleRunOutputs and MultiRunOutputs JavaScript objects).The Outputs object is an array with each element representing a single output of a run or aseries of runs. Note that in case of multi-run experiments, an element can represent an inputvaried across the runs. The aggregationType field is a system field that tells how the results ofindividual runs are aggregated. Consider an example of a single run outputs:

[ { aggregationType: "IDENTITY", inputs: [], outputs: [{name: "Queue size stats", type: "STATISTICS_CONTINUOUS", units: null, value: null}], value: "{"type":"CONTINUOUS","count":1375730,"min":0.0,"max":10.0,"mean":0.9915478405530092, … }" }, { aggregationType: "IDENTITY" inputs: [] outputs: [{name: "Total time in system|Total time in system", type: "HISTOGRAM_DATA", units: null, value: null}] value: "{"statistics":{"type":"DISCRETE","count":1000897,"min":1.6001570096705109, … }" }, { aggregationType: "IDENTITY" inputs: [] outputs: [{name: "Utilization|Server utilization", type: "DOUBLE", units: null, value: null}] value: "0.500358755897554" }, { aggregationType: "IDENTITY" inputs: [] outputs: [{name: "Mean queue size|Mean queue size", type: "DOUBLE", units: null, value: null}] value: "0.9915478375701102" }]

In case of a single simulation run, there is obviously no aggregation, and the value of theaggregationType field is IDENTITY . Besides the aggregationType, each element of a top-levelarray always contains inputs, outputs, and value fields. As there are no varied parameters in asingle run, there are no input descriptors and the inputs field is an empty array in all items.The outputs field is an array with a single element describing the output: its name, type, units,and value, but the value is always null in the descriptor.

The possible values of the type field of an array element are listed in the Input types section.

The actual value of the output is contained in the value field of the top-level array element asan unparsed JSON object. You can find more information on the value formats in the sectionabout data conversion.

Please keep in mind that, although an AnyLogic chart (possibly, containing multiple data items)is a single item in AnyLogic Run configuration, its data items become separate items inAnyLogic Cloud API. Therefore, the name of such item returned by the API comprises |. Forother AnyLogic outputs, such as (explicitly defined) datasets, statistics objects, output objects,the name in AnyLogic API outputs is the same as in AnyLogic. Compare the JS object abovewith the Run configuration screenshot:

In case of multi-run experiments, such as Variation or Monte Carlo, the format of outputsbecomes a bit more complicated. To give you an idea of the format, let us consider the outputsof the parameter variation experiment of the same model that produced the single-run outputsdescribed above:

[ { aggregationType: "ARRAY", inputs: [], outputs: [{name: "Queue size stats", type: "STATISTICS_CONTINUOUS", units: null, value: null}], value: "[{"count":1335978,"min":0.0,"max":10.0,"mean":0.9860041083277306,"variance":0.07920717342721317, … }]" }, { aggregationType: "ARRAY", inputs: [], outputs: [{name: "Total time in system|Total time in system", type: "HISTOGRAM_DATA", units: null, value: null}], value: "[{"statistics":{"type":"DISCRETE","count":999206,"min":1.4401413087034598, … }]" }, { aggregationType: "ARRAY", inputs: [], outputs: [{name: "Utilization|Server utilization", type: "DOUBLE", units: null, value: null}], value: "[0.4497779714401299,0.4750782325123417,0.500358755897554]" }, { aggregationType: "ARRAY", inputs: [], outputs: [{name: "Mean queue size|Mean queue size", type: "DOUBLE", units: null, value: null}], value: "[0.9860040848956356,0.9877473693031751,0.9915478375701102]" }, { aggregationType: "ARRAY", inputs: [{name: "Mean service time",type: "FIXED_RANGE_DOUBLE",units: null,value: "{"min":"1.8","max":"2","step":"0.1 outputs: [], value: "[[1.8],[1.9],[2.0]]" }]

The aggregationType is now ARRAY. As you can see, one of the items in the top-level array (thelast one) now contains a non-empty input field for the input that is being varied. The(unparsed) value fields of the output items are now arrays with multiple elements, forexample, the Queue size stats has an array of three statistics objects in its value field. Thesequence of the output values in the arrays corresponds to the sequence of the varied inputparameter values. Once again: the Cloud clients provided by AnyLogic enable easy iterationsthough the inputs and outputs, see for example the JS MultiRunOutputs class.

Run RequestRun Request contains the type of experiment and the full list of inputs. It does not contain a

reference to the model version, which is passed as a part of the request URL. Below you cansee an example of Run Request for a simulation run:

{ experimentType: "SIMULATION", inputs: [ {name: "{STOP_MODE}", type: "STRING", units: null, value: "STOP_MODE_AT_TIME"}, {name: "{START_TIME}", type: "DOUBLE", units: "SECOND", value: "0"}, {name: "{STOP_TIME}", type: "DOUBLE", units: "SECOND", value: "1000000"}, {name: "{START_DATE}", type: "DATE_TIME", units: null, value: "2019-05-15T00:00"}, {name: "{STOP_DATE}", type: "DATE_TIME", units: null, value: "2019-05-26T13:46:40"}, {name: "{MAX_MEMORY_MB}", type: "INTEGER", units: null, value: "512"}, {name: "Arrival rate", type: "DOUBLE", units: null, value: "1"}, {name: "Mean service time", type: "DOUBLE", units: null, value: "2"}, {name: "Server capacity", type: "INTEGER", units: null, value: 5 }, {name: "Check failure probability", type: "DOUBLE", units: null, value: "0.2"}, {name: "{RANDOM_SEED}", type: "LONG", units: null, value: "1"} ]}

For a parameter variation experiment with one parameter varied in a range, the Run Requestlooks like this:

{ experimentType: "PARAMETER_VARIATION", inputs: [ {name: "{STOP_MODE}", type: "STRING", units: null, value: "STOP_MODE_AT_TIME"}, {name: "{START_TIME}", type: "DOUBLE", units: "SECOND", value: "0"}, {name: "{STOP_TIME}", type: "DOUBLE", units: "SECOND", value: "1000000"}, {name: "{START_DATE}", type: "DATE_TIME", units: null, value: "2019-05-15T00:00"}, {name: "{STOP_DATE}", type: "DATE_TIME", units: null, value: "2019-05-26T13:46:40"}, {name: "{MAX_MEMORY_MB}", type: "INTEGER", units: null, value: "512"}, {name: "Arrival rate", type: "DOUBLE", units: null, value: "1"}, {name: "Mean service time", type: "FIXED_RANGE_DOUBLE", units: null, value: { min : 1.8 , max : 2 , step : 0.1 } }, {name: "Server capacity", type: "INTEGER", units: null, value: 5 }, {name: "Check failure probability", type: "DOUBLE", units: null, value: "0.2"}, {name: "{RANDOM_SEED}", type: "LONG", units: null, value: "1"} ]}

Please note that the value of an input is always a string, which may contain an unparsed JSONlike in case of a range.

Experiment Results RequestExperiment Results Request contains the type of experiment, the full list of inputs, and the listof required outputs. The latter is a string form of the Outputs data object with blank values. Forexample:

{ experimentType: "SIMULATION", inputs: [ {name: "{STOP_MODE}", type: "STRING", units: null, value: "STOP_MODE_AT_TIME"}, {name: "{START_TIME}", type: "DOUBLE", units: "SECOND", value: "0"}, {name: "{STOP_TIME}", type: "DOUBLE", units: "SECOND", value: "1000000"}, {name: "{START_DATE}", type: "DATE_TIME", units: null, value: "2019-05-15T00:00"}, {name: "{STOP_DATE}", type: "DATE_TIME", units: null, value: "2019-05-26T13:46:40"}, {name: "{MAX_MEMORY_MB}", type: "INTEGER", units: null, value: "512"}, {name: "Arrival rate", type: "DOUBLE", units: null, value: "1"}, {name: "Mean service time", type: "DOUBLE", units: null, value: "2"}, {name: "Server capacity", type: "INTEGER", units: null, value: 5 }, {name: "Check failure probability", type: "DOUBLE", units: null, value: "0.2"}, {name: "{RANDOM_SEED}", type: "LONG", units: null, value: "1"} ] outputs: "[{"aggregationType":"IDENTITY","inputs":[],"outputs":[{"name":"Queue size "}

Experiment RunExperiment run contains the unique run id, the model version id, the inputs, the run status,and the message containing unparsed JSON with information about the run (see Experiment

Run State) and can be empty, for example:

{ id: "Ao7KEYv76pyqZFf6QetmAg6InFuJoJMj1WbYaSm17wo", inputs: [ {name: "{STOP_MODE}", type: "STRING", units: null, value: "STOP_MODE_AT_TIME"}, {name: "{START_TIME}", type: "DOUBLE", units: "SECOND", value: "0"}, {name: "{STOP_TIME}", type: "DOUBLE", units: "SECOND", value: "1000000"}, {name: "{START_DATE}", type: "DATE_TIME", units: null, value: "2019-05-15T00:00"}, {name: "{STOP_DATE}", type: "DATE_TIME", units: null, value: "2019-05-26T13:46:40"}, {name: "{MAX_MEMORY_MB}", type: "INTEGER", units: null, value: "512"}, {name: "Arrival rate", type: "DOUBLE", units: null, value: "1"}, {name: "Mean service time", type: "DOUBLE", units: null, value: "2"}, {name: "Server capacity", type: "INTEGER", units: null, value: "5"}, {name: "Check failure probability", type: "DOUBLE", units: null, value: "0.2"}, {name: "{RANDOM_SEED}", type: "LONG", units: null, value: "1"} ], message: "{"title":null,"total":100,"finishedTasks":1,"totalTasks":1,"subRuns":[]}", modelVersionId: "def089c4-96a3-40f2-aefb-de1af471fe2f", outputs: null, status: "COMPLETED"}

The outputs field of the Experiment Run is always empty.

Experiment Run StateExperiment Run State comes in response to a progress request. It contains the status of therun and the message field with the unparsed JSON structure with the run progress details:

{ message: "{"title":null,"total":52,"finishedTasks":0,"totalTasks":1,"subRuns":[]}", status: "RUNNING"}

To obtain the completed fraction of the run, you can call JSON.parse( .message ).total;

The status of a run can be:

"FRESH" - created, not yet started"RUNNING" - currently being executed"COMPLETED" - successfully completed, results are available"FAILED" - execution failed"STOPPED" - cancelled before completion by the user (via GUI or API).

For a completed run, the message field may be an empty string:

{ message: "", status: "COMPLETED"}

For a multiple run experiment, the Experiment Run State will look like this:

{ message: "{"title":null,"total":47,"finishedTasks":0,"totalTasks":11," … }", status: "RUNNING"}

And if you parse the message field, the structure will be:

{ finishedTasks: 0 subRuns: [ {title: null, total: 42, finishedTasks: 2, totalTasks: 5, subRuns: []}, {title: null, total: 42, finishedTasks: 2, totalTasks: 5, subRuns: []} ], title: null, total: 47, totalTasks: 11}

The subRuns field contains information about the batches of individual runs comprising theexperiment.

Animation SVG Run InfoAnimation SVG Run Info comes in response to starting model run with animation.= It containsthe native dimensions of the animation window, the simulation speed, the URL of the nodewhere the simulation is running, and other information:

{ animationHeight: 600, animationSpeed: 10, animationWidth: 1000, experimentRunId: "fbc6a1d8-fa08-4a5c-a171-4631657c1aa7", modelUuid: "493e6789-acf7-4dac-971d-325cb508ea39", restUrl: "b0cc221b-8217-474b-af18-c2d07753187b/", sessionUuid: "b0cc221b-8217-474b-af18-c2d07753187b", version: "8.5.0"}

Input typesInput type is a string constant with the following possible values:

"STRING"

"DOUBLE"

"INTEGER"

"LONG"

"DATE_TIME"

"BOOLEAN"

"RANDOM_DOUBLE"

"RANDOM_INTEGER"

"RANDOM_BOOLEAN"

"FIXED_RANGE_DOUBLE"

"FIXED_RANGE_INTEGER"

"FIXED_RANGE_LONG"

"FULL_RANGE_BOOLEAN"

"INPUT_FILE"

UnitsUnit is a string constant, it can be null, or one of the following types:

"MILLISECOND"

"SECOND"

"MINUTE"

"HOUR"

"DAY"

"WEEK"

"MONTH"

"YEAR"

"MILLIMETER"

"CENTIMETER"

"METER"

"KILOMETER"

"INCH"

"FOOT"

"YARD"

"MILE"

"NAUTICAL_MILE"

"SQ_MILLIMETER"

"SQ_CENTIMETER"

"SQ_METER"

"SQ_KILOMETER"

"SQ_INCH"

"SQ_FOOT"

"SQ_YARD"

"SQ_MILE"

"SQ_NAUTICAL_MILE"

"PER_MILLISECOND"

"PER_SECOND"

"PER_MINUTE"

"PER_HOUR"

"PER_DAY"

"PER_WEEK"

"PER_MONTH"

"PER_YEAR"

"MPS"

"KPH"

"FPS"

"FPM"

"MPH"

"KN"

"MPS_SQ"

"FPS_SQ"

"LITER"

"OIL_BARREL"

"CUBIC_METER"

"KILOGRAM"

"TON"

"LITER_PER_SECOND"

"OIL_BARREL_PER_SECOND"

"CUBIC_METER_PER_SECOND"

"KILOGRAM_PER_SECOND"

"TON_PER_SECOND"

"TURN"

"RADIAN"

"DEGREE"

"RPM"

"RAD_PER_SECOND"

"DEG_PER_SECOND"

Output typesOutput type is a string constant with the following possible values:

"STRING"

"DOUBLE"

"INTEGER"

"LONG"

"DATE_TIME"

"BOOLEAN"

"DATA_SET"

"STATISTICS_DISCRETE"

"STATISTICS_CONTINUOUS"

"HISTOGRAM_DATA"

"HISTOGRAM_2D_DATA"

"MODEL_OUTPUT_NAME"

3 API usage examples3.1 Simulation run without animation (minimalistic)In this example we run a simulation experiment without animation. First, we find the model andits latest version. Next, we specify the input parameters of the model. If simulation with suchinputs has already been completed (and thus, the outputs are stored in Cloud), the outputs aresimply transferred to the web frontend. Otherwise, simulation is run in the fast mode withoutanimation. The outputs in this case are generated and delivered to the frontend.

JavascriptThis is done with the API function ModelRun.getOutputsAndRunIfAbsent().

HTML:

AnyLogic Cloud API Example - Run simulation. Minimalistic

Run simulation The simulation results will be displayed here

JavaScript:

message and copy it to console. Then the finally block is executed.5. Please note that to get the value of a particular output, we need to specify its name

exactly as it is constructed when the model is uploaded to Cloud (for more informationrefer to the Output data object section. The case, however, does not matter: you can useeither lower case or upper case.

It is also worth reminding that the function runSimulation() completes immediately, and thecode fragments written in the then, catch, and finally blocks are invoked later when thecorresponding events occur.

PythonThis is done with the API function ModelRun.get_outputs_and_run_if_absent().

Python:from anylogiccloudclient.client.cloud_client import CloudClient

client = CloudClient("e05a6efa-ea5f-4adf-b090-ae0ca7d16c20")version = client.get_latest_model_version("Service System Demo")inputs = client.create_inputs_from_experiment(version, "Baseline")inputs.set_input("Server capacity", 8)simulation = client.create_simulation(inputs)outputs = simulation.get_outputs_and_run_if_absent()

print("Raw outputs = " + str(outputs.get_raw_outputs()))print("For Server Capacity = " + str(inputs.get_input("Server capacity")))print("Mean queue size = " + str(outputs.value("Mean queue size|Mean queue size")))print("Server utilization = " + str(outputs.value("Utilization|Server utilization")))

Python is considered a backend programming language, that is why the inputs and the outputsare accessible through the console only:

1. The CloudClient object is created, given the API key.2. The server is asked to find the latest version of the model with the name “Service System

Demo”.3. When (and if) such model and version is found, we create the Inputs object with the

default input values.4. We use the set_input() function to change the value of the “Server capacity” parameter

to 8.5. We ask the CloudClient to create a simulation object with the inputs. This is done on the

client side, there is no communication with the server.6. The getOutputsAndRunIfAbsent() function is called, which checks the simulation status:

If such simulation has been completed, it gets the outputsIf such simulation hasn't been run yet, it runs the simulation and waits for theoutputs. The SingleRunOutputs object is returned

7. Finally, the obtained output values and the corresponding input are displayed in theconsole using the API of SingleRunOutputs and Inputs.

If an error occurs during any step, the error message will be displayed in the console.

Please note that to get the value of a particular output, we need to specify its name exactly asit is constructed when the model is uploaded to Cloud (for more information refer to the Outputdata object section. The case, however, does not matter: you can use either lower case orupper case.

JavaThis is done with the API function ModelRun.getOutputsAndRunIfAbsent().

Java:

package com.anylogic.cloud.java_api_example;

import com.anylogic.cloud.clients.client_8_5_0.*;import com.anylogic.cloud.service.open_8_5_0.api.project.*;

public class Example { private static final String API_KEY = "4b7494a6-8c4e-4fb2-b4a8-9d829dcbb7a6"; private static final String MODEL_ID = "a56057c6-b937-4539-8bdc-ab4e5f8fe86a"; private static final String DOUBLE_INPUT = "Server capacity"; private static final String DOUBLE_OUTPUT = "Average performance";

public static void main(String[] args) { singleSimulationRun(); }

private static void singleSimulationRun() { System.out.println("A single simulation run with Double input = 20.0"); AnyLogicCloudClient client = new AnyLogicCloudClient(API_KEY); Model model = client.getModelById(MODEL_ID); ModelVersion version = client.getLatestModelVersion(model); Inputs inputs = client.createDefaultInputs(version); inputs.setInput(DOUBLE_INPUT, 20.0); SimulationRun simulation = client.createSimulation(inputs); SingleRunOutputs outputs = simulation.getOutputsAndRunIfAbsent(); // will exit upon run completion System.out.println(outputs.value(DOUBLE_OUTPUT)); }}

The Example class contains multiple values that will be used for input.

1. The AnyLogicCloudClient class is constructed, given the API key.2. The server is asked to find the model with the given model id.3. The server is asked to find the latest version of the model.4. When (and if) such model and version is found, we create the Inputs object with the

default input values.5. We use the setInput function to change the value of the “Server capacity” parameter to

20.0. Other inputs will keep their default values.6. We ask the AnyLogicCloudClient to create a simulation object with the inputs. This is

done on the client side, there is no communication with the server.7. The getOutputsAndRunIfAbsent() function is called, which checks the simulation status:

If such simulation has been completed, it gets the outputsIf such simulation hasn't been run yet, it runs the simulation and waits for theoutputs. The SingleRunOutputs object is returned

8. Finally, the output value for the “Average performance” field is displayed in the Javaconsole using the API of SingleRunOutputs.

If an error occurs during any step, the error message will be displayed in the Java console.

Please note that to get the value of a particular output, we need to specify its name exactly asit is constructed when the model is uploaded to Cloud (for more information refer to theOutput data object section. The case, however, does not matter: you can use either lower caseor upper case.

3.2 Querying simulation results of a completed runAs you know, AnyLogic Cloud stores the input/output pairs of all the ever-completed simulationruns. In this example, we will show you how to query the outputs of a completed model run(which is identified by the inputs). If the results exist, they will be displayed, otherwise, we willdisplay the corresponding message instead of running the simulation as we did in the previous

example.

JavascriptThe key function used here is ModelRun.getOutputs().

HTML:

AnyLogic Cloud API Example - Query outputs of a completed run

Server capacity: 5 Query outputs The simulation results will be displayed here

JavaScript:let cloudClient = create("e05a6efa-ea5f-4adf-b090-ae0ca7d16c20");

let parameterValue;let parameterRange;let queryButton;let info;

window.onload = () => { parameterValue = document.getElementById( "parameter-value" ); parameterRange = document.getElementById( "parameter-range" ); queryButton = document.getElementById( "query-button" ); info = document.getElementById( "info" );};

function queryOutputs() { parameterRange.disabled = true; queryButton.disabled = true; cloudClient.getModelByName( "Service System Demo" ) .then( model => cloudClient.getLatestModelVersion( model ) ) .then( version => { let inputs = cloudClient.createDefaultInputs( version ); inputs.setInput( "Server capacity", parameterRange.value); let simulation = cloudClient.createSimulation(inputs); info.innerHTML = "Getting outputs..."; return simulation.getOutputs(); }) .then( outputs => { let html = "Mean queue size = " + outputs.value( outputs.findNameIncluding("Mean Queue Size") ) + "
"; html += "Server utilization = " + outputs.value( outputs.findNameIncluding("Server utilization") ) + "
" + error.message; console.error( error ); }) .finally( () => { parameterRange.disabled = false; queryButton.disabled = false; });}

function changeValueText() { parameterValue.innerText = parameterRange.value;}

Try now

In the HTML code there is a range input element that we use to set the value of the Server

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.query.html

capacity. Having constructed the inputs and the simulation objects, we callsimulation.getOutputs(). If the outputs exist, they are returned by Promise and we get intothe following then block. If there are no outputs, an error occurs, we process to the catch blockand display the error. However, the same catch block is executed if any other type of erroroccurs. If you want to invoke a specific handler in case of absent results, you can modify thecode in the following way:

JavaScript:…return simulation.getOutputs() .catch( error => { if( error.status == 404 ) { //custom handler code console.error( "Simulation results not found for these inputs" ); } throw new Error( "Outputs not found for Server Capacity = " + parameterRange.value ); });…

PythonThe key function used here is ModelRun.get_outputs().

Python:from anylogiccloudclient.client.cloud_client import CloudClient

client = CloudClient("e05a6efa-ea5f-4adf-b090-ae0ca7d16c20")model = client.get_model_by_name("Service System Demo")version = client.get_latest_model_version(model)inputs = client.create_default_inputs(version)inputs.set_input("Server capacity", 8)simulation = client.create_simulation(inputs)outputs = simulation.get_outputs()

print("Mean queue size: " + str(outputs.value("Mean queue size|Mean queue size")))

We use the set_input() function to change the value of the “Server capacity” parameter to 8.Having constructed the inputs and the simulation objects, we call simulation.get_outputs().If the outputs exist, they are returned. If there are no outputs, an error occurs.

JavaThe key function used here is ModelRun.getOutputs().

Java:





private static void singleSimulationRunGetResultsOfCompletedRun() { System.out.println("Getting results of already completed run with Server capacity = 20.0"); AnyLogicCloudClient client = new AnyLogicCloudClient(API_KEY); Model model = client.getModelById(MODEL_ID); ModelVersion version = client.getLatestModelVersion(model); Inputs inputs = client.createDefaultInputs(version); inputs.setInput(DOUBLE_INPUT, 20.0); SimulationRun simulation = client.createSimulation(inputs); SingleRunOutputs outputs = simulation.getOutputs(); System.out.println(outputs.value(DOUBLE_OUTPUT)); }}


We use the setInput() function to change the value of the “Server capacity” parameter to20.0. Having constructed the inputs and the simulation objects, we callsimulation.getOutputs(). If the outputs exist, they are returned. If there are no outputs, anerror occurs.

3.3 Simulation run with progress pollingIn case simulation is run without animation it makes sense to have some progress indication.

JavascriptIn this example we use the function ModelRun.getProgress() to obtain the progress of therunning simulation. We also show a different way of running the simulation and getting resultsvia the sequence of run(), waitForCompletion(), and getOutputs() function calls.

HTML:

AnyLogic Cloud API Example - Simulation with Progress indication

Run simulation The simulation results will be displayed here

JavaScript:


let runButton;let progress;let info;let simulation;

window.onload = () => { runButton = document.getElementById( "run-button" ); progress = document.getElementById( "progress" ); info = document.getElementById( "info" );};

function runSimulation() { runButton.disabled = true; cloudClient.getLatestModelVersion( "Service System Demo" ) .then( version => { let inputs = cloudClient.createDefaultInputs( version ); inputs.setInput( "Server capacity", 21 ); inputs.setInput( "{STOP_TIME}", 10000000 ); simulation = cloudClient.createSimulation(inputs); startPolling(); return simulation.run(); }) .then( simulation => simulation.waitForCompletion() ) .then( simulation => simulation.getOutputs() ) .then( outputs => { let html = "Mean queue size = " + outputs.value( "Mean queue size|Mean queue size" ) + "
"; html += "Server utilization = " + outputs.value( "Utilization|Server utilization" ) + "
" + error.message; console.error( error ); }) .finally( () => { stopPolling(); runButton.disabled = false; });}

let pollingInterval;

function startPolling() { pollingInterval = setInterval( () => { simulation.getProgress() .then( progressinfo => { if( progressinfo ) { //can be undefined in the beginning progress.value = progressinfo.total; } }); }, 1000 );}

function stopPolling() { setTimeout( () => clearInterval( pollingInterval ), 2000 );}

Try now

During the standard construction of the inputs, we change the “system” input {STOP_TIME} to abigger value to make the simulation run longer, so we can really see the progress bar moving.Such input exists in every model uploaded to Cloud. However, if a run with the same stop timeand other inputs has been performed already, the simulation won’t run, and the outputs will bedelivered almost instantly. So, to watch the progress moving, consider setting other values forthe inputs.

The function startPolling() is called just before simulation.run(), and initiates a repeatedcall of simulation.getProgress() with one second interval. The function getProgress() returns

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.progress.html

information about the progress by Promise. For a simple simulation run, we are only interestedin the total field. For multi-run experiments it contains more details. Please note that theresult may also be an empty object if we poll too soon (while the run has not yet been createdon the server), therefore, we need to check the existence of the polling result. The functionstopPolling() is called once the simulation results have been delivered (or an error occurs). Itclears the one second interval but waits for additional two seconds to make sure that the finalprogress value has been received.

The call of simulation.run() initiates the simulation run (only if such run has not been donebefore) and returns the same simulation object by Promise. It does not wait for the simulationto complete. To wait for the experiment to complete, we use the functionsimulation.waitForCompletion(), which also returns the same object. It is only now that wequery the simulation results by calling simulation.getOutputs(). This sequence is here solelyfor demo purposes; it could be replaced by a single call ofsimulation.getOutputsAndRunIfAbsent().

PythonIn this example we use the function ModelRun.get_progress() to obtain the progress of therunning simulation. We also show a different way of running the simulation and getting resultsvia the sequence of run(), wait_for_completion(), and get_outputs() function calls.

Python:import threadingimport time

from anylogiccloudclient.client.cloud_client import CloudClient

def _update_progress(s): while s.get_status() == "FRESH" or s.get_status() == "RUNNING": print("Progress: " + str(s.get_progress()["total"]) + "%") time.sleep(5)

client = CloudClient("e05a6efa-ea5f-4adf-b090-ae0ca7d16c20")version = client.get_latest_model_version("Service System Demo")inputs = client.create_default_inputs(version)inputs.set_input("Server capacity", 21)inputs.set_input("{STOP_TIME}", 10000000)simulation = client.create_simulation(inputs)

simulation.run()

progress_thread = threading.Thread(target=_update_progress, args=(simulation,))progress_thread.start()

simulation.wait_for_completion()outputs = simulation.get_outputs()

print("Mean queue size: " + str(outputs.value("Mean queue size|Mean queue size")))

During the standard construction of the inputs, we change the “system” input {STOP_TIME} to abigger value to be able to observe the actual progress by making the simulation run longer.Such input exists in every model uploaded to Cloud. However, if a run with the same stop timeand other inputs has been performed already, the simulation won’t run, and the outputs will bedelivered almost instantly. So, to watch the progress moving, consider setting other values forthe inputs.

We use the progress_thread.start() function, which is called after simulation.run(). Itinitiates a repeated call of s.get_progress(), which returns information about the progress.For a simple simulation run, we are only interested in the total field. For multi-runexperiments it contains more details. The function time.sleep() is called once the simulationis completed. It waits for additional 5 seconds to make sure that the final progress value hasbeen received.

The call of simulation.run() initiates the simulation run (only if such run has not been donebefore) and returns the same simulation object. It does not wait for the simulation tocomplete. To wait for the experiment to complete, we use the functionsimulation.wait_for_completion(), which also returns the same object. It is only now that wequery the simulation results by calling simulation.get_outputs(). This sequence is here solelyfor demo purposes; it could be replaced by a single call ofsimulation.get_outputs_and_run_if_absent().

JavaAn ability to track the running simulations via the Java client is coming soon.

3.4 Running a custom workflow – a mix of parallel andsequential simulationsNow, let’s implement a custom workflow where some simulations are run in parallel and some– sequentially, based on the results of other simulations. This scenario may be useful for thosewho want to set up e.g. a custom optimization algorithm in AnyLogic Cloud.

JavascriptHTML:

AnyLogic Cloud API Example - Custom workflow

Run 2+1 simulations The simulation results will be displayed here

JavaScript:


let version;let runButton;let info;


let sc1 = 4;let sc2 = 9;let sc3;

function runSimulations() { runButton.disabled = true; cloudClient.getLatestModelVersion( "Service System Demo" ) .then( v => { version = v; //create two inputs instances with different parameter values let inputs1 = cloudClient.createDefaultInputs( version ); let inputs2 = cloudClient.createDefaultInputs( version ); inputs1.setInput( "Server capacity", sc1 ); inputs2.setInput( "Server capacity", sc2 ); //create two simulation objects with different inputs let simulation1 = cloudClient.createSimulation( inputs1 ); let simulation2 = cloudClient.createSimulation( inputs2 ); info.innerHTML = "Running two parallel simulations...
"; //run the two simulations in parallel, wait for both results return Promise.all( [simulation1.getOutputsAndRunIfAbsent(), simulation2.getOutputsAndRunIfAbsent()] ); }) .then( outputarray => { //both outputs are here let su1 = outputarray[0].value( "Utilization|Server utilization" ); let su2 = outputarray[1].value( "Utilization|Server utilization" ); let html = "Two parallel simulations completed.
"; html += "With " + sc1 + " servers, Server utilization = " + su1 + "
"; //based on the results, set up the inputs for the third simulation sc3 = (su1 + su2) > 0.4 ? sc2-1 : sc1+1; let inputs3 = cloudClient.createDefaultInputs( version ); inputs3.setInput( "Server capacity", sc3 ); let simulation3 = cloudClient.createSimulation( inputs3 ); html += "Running third simulation with " + sc3 + " servers...
"; info.innerHTML += html return simulation3.getOutputsAndRunIfAbsent(); }) .then( outputs3 => { let su3 = outputs3.value( "Utilization|Server utilization" ); let html = "Third simulation completed.
"; info.innerHTML += html }) .catch( error => { info.innerHTML = error.status + "

Try now

In this scenario, we first perform two simulation runs in parallel with the Server Capacityparameter set to 4 in one run and 9 in another. The two runs are initiated by callingsimulation1.getOutputsAndRunIfAbsent() and simulation2.getOutputsAndRunIfAbsent(). Thefunction getOutputsAndRunIfAbsent() (as actually all functions in AnyLogic Cloud JavaScriptAPI that involve communication with the server) is asynchronous – it immediately returns aPromise, and then we need to provide the handler in the then block. In this case we have twoPromise objects from the two runs – and we need to wait for both to complete. This is

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.workflow.html

accomplished by using the Promise.all() function returning a single Promise, which resolvesafter all the promises (passed as an iterable array in our case) have resolved. The outputs ofsimulation runs performed in parallel are returned also as an array in the same order. In thethen block that follows we analyze the values of Server Utilization in both runs and set up theinput of the third simulation run based on those values.

Please note that, when you run multiple simulations in parallel manually, like in this example,each call of ModelRun.getOutputsAndRunIfAbsent() or ModelRun.waitForCompletion()performs its own independent polling, therefore many parallel runs may result in high HTTPtraffic. If that is suspected, consider changing the optional parameter pollingPeriod of thesefunctions.

PythonPython:


capacities = [4, 9]client = CloudClient("e05a6efa-ea5f-4adf-b090-ae0ca7d16c20")version = client.get_latest_model_version("Service System Demo")

inputs = [client.create_default_inputs(version) for num in range(2)][inputs[num].set_input("Server capacity", capacities[num]) for num in range(2)]

simulations = [client.create_simulation(i) for i in inputs][s.run() for s in simulations][s.wait_for_completion() for s in simulations]

outputs = [s.get_outputs() for s in simulations]for o in outputs: print("Mean queue size: " + str(o.value("Mean queue size|Mean queue size")))

In this scenario, we first perform two simulation runs in parallel with the Server Capacityparameter set to 4 in one run and 9 in another by the range() function. The two runs areinitiated by calling s.run().

The outputs of simulation runs performed in parallel are returned also as an array in the sameorder.

Please note that, when you run multiple simulations in parallel manually, like in this example,each call of s.wait_for_completion() performs its own independent polling, therefore manyparallel runs may result in high HTTP traffic. If that is suspected, consider changing theoptional parameter polling_period of these functions.

JavaWill be added soon.

3.5 Running parameter variationIn this example, we will run a parameter variation experiment. One of the input parameters willbe varied in range. To demonstrate one more feature of the AnyLogic Cloud API, we will takethe input values from an existing simulation experiment defined in the standard AnyLogicCloud web interface and change a parameter value from a scalar to a range.

JavascriptHTML:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

AnyLogic Cloud API Example - Parallel Simulations

Run variation The parameter variation results will be displayed here


let runButton;let info;


function runVariation() { runButton.disabled = true; cloudClient.getLatestModelVersion( "Service System Demo" ) .then( version => { return cloudClient.createInputsFromExperiment( version, "Baseline" ); }) .then( inputs => { inputs.setRangeInput( "Mean service time", 1.8, 2, 0.1 ); let variation = cloudClient.createParameterVariation( inputs ); info.innerHTML = "Running parameter variation...
"; return variation.getOutputsAndRunIfAbsent( ["Total time in system|Total time in system"] ); }) .then( outputs => { let html = "Parameter variation completed.
"; let invalues = outputs.getValuesOfInput("Mean service time"); let outvalues = outputs.getValuesOfOutput("Total time in system|Total time in system"); for( let i=0; i { info.innerHTML = error.status + "

Try now

To reuse the set of inputs from an experiment defined in the AnyLogic Cloud web interface weuse the function CloudClient.createInputsFromExperiment() instead ofcreateDefaultInputs(). Having copied the inputs of the "Baseline" experiment, we changethe input "Mean service time" to a range type (from 1.8 to 2.0 with step 0.1) by callingInputs.setRangeInput(). Therefore three simulation runs are to be performed.

Then we need to create a ModelRun object of parameter variation type, which is done by theCloudClient.createParameterVariation() function.

The run of parameter variation is invoked by calling the getOutputsAndRunIfAbsent() functionjust like in our previous examples, but there is one important difference. Full outputs of amultiple run experiment may be a very large piece of data, so the API user has to explicitlyspecify which outputs need to be delivered. This is done by listing the output names in the

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.variation.html

array passed to getOutputsAndRunIfAbsent() or getOutputs() as a parameter. In this example,we are interested in the "Total time in system|Total time in system" output. If theparameter is omitted for a multi run experiment, only scalar outputs will be returned, if any.

Outputs of a multi run experiment are returned as a MultiRunOutputs object, which has anumber of functions simplifying navigation. In this simple example we get array of the inputvalues and the corresponding array of the output values, and display them.

PythonPython:


client = CloudClient("e05a6efa-ea5f-4adf-b090-ae0ca7d16c20")version = client.get_latest_model_version("Service System Demo")inputs = client.create_inputs_from_experiment(version, "Baseline")inputs.set_range_input("Mean service time", 1.8, 2, 0.1)variation = client.create_parameter_variation(inputs)outputs = variation.get_outputs_and_run_if_absent()

print("Mean queue size: " + str(outputs.get_values_of_output("Mean queue size|Mean queue size")))

To reuse the set of inputs from an experiment defined in the AnyLogic Cloud web interface weuse the function CloudClient.create_inputs_from_experiment() instead ofcreate_default_inputs(). Having copied the inputs of the "Baseline" experiment, we changethe input "Mean service time" to a range type (from 1.8 to 2.0 with step 0.1) by callingInputs.set_range_input(). Therefore, three simulation runs are to be performed.

Then we need to create a ModelRun object of parameter variation type, which is done by theCloudClient.create_parameter_variation() function.

The run of parameter variation is invoked by calling the get_outputs_and_run_if_absent()function just like in our previous examples, but there is one important difference. Full outputsof a multiple run experiment may be a very large piece of data, so the API user has to explicitlyspecify which outputs need to be delivered. This is done by listing the output names in thearray passed to get_outputs_and_run_if_absent() or get_outputs() as a parameter. In thisexample, we are interested in the "Mean queue size|Mean queue size" output. If theparameter is omitted for a multi run experiment, only scalar outputs will be returned, if any.

Outputs of a multi run experiment are returned as a MultiRunOutputs object, which has anumber of functions simplifying navigation.

JavaJava:



import java.util.Arrays;



private static void parameterVariation() { System.out.println( "A parameter variation run with Double input varied from 20.0 to 180.0 with step 20.0" ); AnyLogicCloudClient client = new AnyLogicCloudClient(API_KEY); Model model = client.getModelById(MODEL_ID); ModelVersion version = client.getLatestModelVersion(model); Inputs inputs = client.createDefaultInputs(version); inputs.setRangeInput(DOUBLE_INPUT, 20.0, 180.0, 20.0); ParameterVariationRun variation = client.createParameterVariation(inputs); MultiRunOutputs outputs = variation.getOutputsAndRunIfAbsent(Arrays.asList(DOUBLE_OUTPUT)); // will exit upon run completion System.out.println(outputs.getValuesOfOutput(DOUBLE_OUTPUT)); }}


Here, we use the Inputs.setRangeInput() function to change the value of the “Servercapacity” input to a range type, from 20.0 to 180.0 with step 20.0. Therefore, nine simulationruns are to be performed.

Then we need to create a ModelRun object of the parameter variation type, which is done bythe AnyLogicCloudClient.createParameterVariation() function.

The run of parameter variation is invoked by calling the getOutputsAndRunIfAbsent() functionjust like in our previous examples, but there is one important difference. Full outputs of amultiple run experiment may be a very large piece of data, so the API user has to explicitlyspecify which outputs need to be delivered. This is done by listing the output names in thearray passed to getOutputsAndRunIfAbsent() or getOutputs() as a parameter. In this example,we are interested in the “Average performance” output. If the parameter is omitted for a multirun experiment, only scalar outputs will be returned, if any.

Outputs of a multi run experiment are returned as a MultiRunOutputs object, which has anumber of functions simplifying navigation.

3.6 Simulation run with animation (minimalistic)The minimalistic example of embedding the animation of a cloud-based model into a web pagewould look like the following.

HTML:

AnyLogic Cloud API Example - Run animation. Minimalistic

Run animation


function runAnimation() { runButton = document.getElementById( "run-button" ); runButton.disabled = true; cloudClient.getLatestModelVersion( "Bass Diffusion Demo 8.5.0" ) .then( version => { let inputs = cloudClient.createDefaultInputs( version ); inputs.setInput( "Contact Rate", 30 ); return cloudClient.startAnimation( inputs, "animation-container" ); }) .then( animation => { return animation.waitForCompletion(); }) .catch( error => { console.error( error ); }) .finally( () => { runButton.disabled = false; });}

Try now

Within the HTML code you should create the animation placeholder. In this example it is theinitially empty 1200x700 element, with the "animation-container" id. Then, when theuser presses the Run animation button, the function runAnimation() is called. It disables thebutton, searches for the latest version of the model, creates a default input set, and changesone of the input values. The call of cloudClient.startAnimation() launches the model,connects the model to the frontend, and starts streaming animation into the providedcontainer. That call completes as the HTTP request completes and returns the Animation objectby Promise. Then we use animation.waitForCompletion() to wait for the user to press Stop.Please note that even if the animated simulation finishes (e.g. reaches its stop time), it is notconsidered as stopped until either of the following:

The user presses the Stop button on the animation control panelThe server decides to stop it for any reason

The finally block is then executed and re-enables the Run button.

3.7 Animated run with external pause and resumebuttons and state pollingThis example is a bit more sophisticated than the previous one: we will add buttons to pauseand resume the simulation. The key functions of the Animation object used here are pause(),resume(), and getState().

HTML:

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.animation.html

AnyLogic Cloud API Example - Animation. Pause Resume

Run animation Pause Resume

JavaScript:


let runButton;let pauseButton;let resumeButton;let animation;

window.onload = () => { runButton = document.getElementById( "run-button" ); pauseButton = document.getElementById( "pause-button" ); resumeButton = document.getElementById( "resume-button" );};

function runAnimation() { runButton.disabled = true; cloudClient.getModelByName( "Bass Diffusion Demo 8.5.0" ) .then( model => cloudClient.getLatestModelVersion( model ) ) .then( version => { let inputs = cloudClient.createDefaultInputs( version ); inputs.setInput( "Contact Rate", 40 ); return cloudClient.startAnimation( inputs, "animation-container" ); }) .then( a => { animation = a; startPolling(); return animation.waitForCompletion(); }) .catch( error => { console.error( error ); }) .finally( () => { stopPolling(); runButton.disabled = false; pauseButton.disabled = true; resumeButton.disabled = true; });}

function pauseAnimation() { pauseButton.disabled = true; animation.pause();}

function resumeAnimation() { resumeButton.disabled = true; animation.resume();}

let pollingInterval;

function startPolling() { pollingInterval = setInterval( () => { animation.getState() .then( state => { pauseButton.disabled = state != "RUNNING"; resumeButton.disabled = state != "PAUSED"; }); }, 500 );}

function stopPolling() { clearInterval( pollingInterval );}

Try now

In the HTML code, there are two new buttons above the animation container that are initiallydisabled. In JavaScript, we remember these elements as the page gets loaded. We alsoremember the Animation object returned by cloudClient.startAnimation() by Promise. Theactions assigned to the buttons simply call pause() and resume() of that object. What is more

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.pause_resume.html

interesting, is the animation state polling. Once the animation starts, we begin to poll its stateevery 0.5 second, see the function startPolling(). A call of getState() returns the animationstate by Promise, and we use it to enable or disable the buttons. The polling is stopped oncethe model is stopped or an error occurs, see the finally block.

Please note that, in animated run, the inputs are not validated until they are passed to themodel. Therefore, if there is an error in the input values (such as a type error), the model willfail to start and you will see an error message within the animation window, but the catch blockwon’t be reached.

Also, in this example we show a different, more general, way of getting to the latest version ofthe model: first, we get the Model object by its name, then we ask for the latest version of themodel.

3.8 Animated run with external control of a modelparameterIn this example we will show how to control a model input parameter while the model isrunning using the AnyLogic Cloud API and how to call a function defined in the model. We willrun the model with the default input parameter value and provide external HTML controls tochange it. The key functions used here are setValue() and callFunction().

HTML:

AnyLogic Cloud API Example - Animation. Parameter Control

Run animation Reset parameter

JavaScript:


let runButton;let parameterRange;let resetButton;let animation;

window.onload = () => { runButton = document.getElementById( "run-button" ); parameterRange = document.getElementById( "parameter-range" ); resetButton = document.getElementById( "reset-button" );};

function runAnimation() { runButton.disabled = true; cloudClient.getLatestModelVersion( "Bass Diffusion Demo 8.5.0" ) .then( version => { let inputs = cloudClient.createDefaultInputs( version ); return cloudClient.startAnimation( inputs, "animation-container" ); }) .then( a => { animation = a; parameterRange.disabled = false; resetButton.disabled = false; return animation.waitForCompletion(); }) .catch( error => { console.error( error ); }) .finally( () => { runButton.disabled = false; parameterRange.disabled = true; resetButton.disabled = true; });}

function changeParameter() { animation.setValue( "experiment.root.ContactRate", parseFloat( parameterRange.value ) );}

function resetParameter() { parameterRange.value = 30; animation.callFunction( "experiment.root.set_ContactRate", [30] );}

Try now

In the HTML code, there is a slider and a button; initially these controls are disabled.

The function changeParameter() uses the AnyLogic Cloud API function setValue(), the firstparameter of which is the path to the object whose value we wish to set. The path shouldalways start with the word "experiment" that is followed by "root" in most cases: "experiment.root" takes you to the root agent of the model, typically this is the (only) instanceof the class Main. As our Contact Rate parameter is located in Main, the full path to it is"experiment.root.ContactRate". Please note that we are using the “original” Java name of theparameter here and not its UI label “Contact Rate”! Also, as the parameter is numeric, weneed to convert parameterRange.value, which is a string, to a float number.

Similarly, the resetParameter() function uses the API function callFunction() to force thevalue of Contact Rate to 30. It is done by invoking the function set_ContactRate() defined inthe model class Main (in this case, the function was auto-generated by AnyLogic, but it couldbe a user-defined function). The path to the function is obviously"experiment.root.set_ContactRate" and the arguments of the function call must be passed asa JavaScript array. In our case there is only one parameter – the new value 30. The functionsdefined in the model by the user are called in exactly same way.

3.9 Retrieving information from a running animated

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.parameter_control.html

modelIn this example, we will retrieve information from a running model using the getValue()function of the Animation object.

HTML:

AnyLogic Cloud API Example - Animation. Get data

Run animation Get scalar value Get dataset The data retrieved from the model will be displayed here

JavaScript:


let runButton;let getScalarButton;let getDataSetButton;let info;let animation;

window.onload = () => { runButton = document.getElementById( "run-button" ); getScalarButton = document.getElementById( "get-scalar-button" ); getDataSetButton = document.getElementById( "get-dataset-button" ); info = document.getElementById( "info" );};

function runAnimation() { runButton.disabled = true; cloudClient.getLatestModelVersion( "Bass Diffusion Demo 8.5.0" ) .then( version => { let inputs = cloudClient.createDefaultInputs( version ); return cloudClient.startAnimation( inputs, "animation-container" ); }) .then( a => { animation = a; getScalarButton.disabled = false; getDataSetButton.disabled = false; return animation.waitForCompletion(); }) .catch( error => { info.innerText = error.message; console.error( error ); }) .finally( () => { runButton.disabled = false; getScalarButton.disabled = true; getDataSetButton.disabled = true; });}

function getScalarValue() { let value = animation.getValue( "experiment.root.Adopters" ) .then( value => { info.innerText = "Adopters = " + value; });}

function getDataSet() { let value = animation.getValue( "experiment.root._ds_Adopters" ) .then( value => { info.innerText = "Adopters over time: time=[" + value.dataX + "] Adopters=[" + value.dataY + "]"; });}

Try now

In the HTML code there are two buttons: one for querying a scalar value, and another forquerying a dataset (both buttons are initially disabled), and a element to display theobtained information.

The first parameter of getValue() is the full path to the object being accessed, which startswith “experiment.root” (just like in setValue() and callFunction() in the previous example).The scalar value is the System Dynamics variable Adopters, and the dataset is the oneautomatically created for the same variable (in AnyLogic such datasets are auto-generatedand have prefix “_ds_”; in case you have a user-defined dataset, you should obviously use thatdataset’s name).

The structure of the object returned by getValue() depends on its type. For primitive types it isquite straightforward, for complex types please consult the Data conversion section tounderstand the Java -> JSON conversion rules. In this example, the AnyLogic DataSet Javaobject is converted into a JSON object with dataX and dataY fields. Should we have a custom

https://cloud.anylogic.com/files/api-8.5.0/docs/examples/index.get_data.html

chart (like Plotly or Tableau chart) as a part of our frontend, we could feed that data into thechart to visualize it, possibly with live updates of certain frequency.

4 JavaScript API4.1 Obtaining the JavaScript clientJavaScript API is used to build custom web interfaces for cloud-based AnyLogic models with orwithout animation. To start using the API, follow these steps:

1. Obtain the cloud_client library by adding the tag to the head of your webpage:

2. Obtain the API key in the AnyLogic Cloud web UI.3. Create a new instance of the CloudClient object

cloudClient = CloudClient.create( ) if you are using the public AnyLogicCloud, orcloudClient = CloudClient.create( , );

4. Use the API to work with the cloud-based models.

The index.html and main.js files contain a simple example of the API usage and may be usefulto look at.

Please keep in mind that:

AnyLogic Cloud JavaScript API is fully asynchronous and extensively uses the PromisetechnologyYour IDE compiler settings should allow ECMAScript 6 JavaScript version

4.2 JavaScript API referenceAnyLogic JavaScript API is purely asynchronous (see Synchronous and asynchronous API),therefore it makes sense to familiarize yourself with JavaScript Promise technology.

Another thing to keep in mind is that the API treats names (e.g. model, experiment, input, andoutput names) as case-insensitive.

CloudClient classThe CloudClient class is responsible for authentication and communication with the AnyLogicCloud. Typically, there is only one object of class CloudClient in your JavaScript code.

static create(apiKey, host) - a static function that creates the API client with the given APIkey, and optionally the host name. If the host is omitted, the public cloud host namehttps://cloud.anylogic.com is assumed.

getModels() - returns available models as an array of Model objects by Promise.

getModelById(id) - returns the Model object with a given id by Promise.

getModelByName(name) - returns the Model object with a given name by Promise.

getModelVersionById(model, versionId) - returns the Version object of a given Model with agiven id by Promise.

getModelVersionByNumber(model, versionNumber) - returns the Version object of a given Modelwith a given number by Promise (version numbering starts with 1).

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promiseshttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises

getLatestModelVersion(modelorname) - returns the latest Version object of a given model(which can be either a Model, or a model name) by Promise.

createDefaultInputs(version) - creates and returns an Inputs object for a given modelVersion with default input values.

createInputsFromExperiment(version, experimentName) - creates and returns by Promise theInputs object for a given model Version object copied from the experiment with the givenname.

createSimulation(inputs) - creates and returns a ModelRun object of type SIMULATION with thegiven Inputs (the model and the version are identified by the inputs).

createParameterVariation(inputs) - creates and returns a ModelRun object of typePARAMETER_VARIATION with the given Inputs (the model and the version are identified by theinputs).

startAnimation(inputs, divId) - starts an animated model run with the given Inputs (whichfully identify the model and the model version), and embeds the animation into the HTMLelement with the given id. Constructs and returns the corresponding Animation object byPromise.

Inputs classAn object of Inputs class is constructed in preparation of a model run (of any kind) by callingthe CloudClient functions createDefaultInputs() or createInputsFromExperiment() andcontains full information about the model, model version, and the input values. It should not beconfused with the inputs field in the Version object.

getInput(name) - returns the value (an object) of the input with a given name. See Dataconversion section for possible types.

setInput(name, value) - sets the value of the input with a given name.

setRangeInput(name, min, max, step) - sets a range for the input with a given name (in aparameter variation experiment).

Inputs of distribution type (for Monte Carlo 2nd order experiments) are coming in futurereleases of AnyLogic Cloud API.

SingleRunOutputs classAn object of this class is returned after a call of getOutputs() or getOutputsAndRunIfAbsent()of a ModelRun constructed for a single run simulation experiment.

names() - returns the array with all output names.

findNameIncluding( namePart ) - searches for an output name that has namePart as asubstring and returns it. If there is no such name or more than one such name is found,throws Error. This function is useful because full names of the outputs may be complex, seeOutputs data object.

value( name ) - returns the value of the output with a given name. The type of value dependson the output, see Data conversion section.

getRawOutputs() - returns an array of all output items, each item has fields name, type, units,and value. For possible values of type and units field see Output types and Units sectionscorrespondingly. The value field contains an object constructed as described in Dataconversion section. This is an example of raw outputs:

[ { name: "Queue size stats", type: "STATISTICS_CONTINUOUS", units: null, value: { count: 1255584, max: 7, mean: 0.9988466028875719, min: 0, totalTime: 999999.2699032243, type: "CONTINUOUS", variance: 0.0027334062484944965 } }, { name: "Total time in system|Total time in system", type: "HISTOGRAM_DATA", units: null, value: { hits: (20) [800912, 159870, 29594, 5804, 3399, 1073, 257, 56, 12, 9, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0], hitsOutHigh: 0, hitsOutLow: 0, intervalWidth: 1.6, lowerBound: 1.6, statistics:{ count: 1000987, max: 18.533258249757637, mean: 2.5012383408878067, min: 1.6001570096705109, type: "DISCRETE", variance: 1.2835661096259896 } } }, { name: "Utilization|Server utilization", type: "DOUBLE", units: null, value: 0.31275860811685163, }, { name: "Mean queue size|Mean queue size", type: "DOUBLE", units: null, value: 0.9988466025848514 }]

MultiRunOutputs classAn object of this class is returned after a call of getOutputs() or getOutputsAndRunIfAbsent()of a ModelRun constructed for a parameter variation or other multi run experiment. It simplifiesnavigation within the complex outputs structure. Keep in mind that you need to explicitlyspecify the required outputs when calling getOutputs() functions.

getInputNames() - returns the array of names of inputs that are varied across runs.

getOutputNames() - returns the array of names of requested outputs.

getValuesOfInput( name ) - returns the array of values of the input with a given name acrossall runs in some fixed sequence. Note that you can only query values of the varied inputs.The fixed inputs are not stored in MultiRunOutputs.

getValuesOfOutput( name ) - returns the array of values of the output with a given nameacross all runs in some fixed sequence. This function can be used together withgetValuesOfInput().

getRawData() - returns a table (a two-dimensional array) with values of all variable inputs andall outputs with a header row. For example, here is the raw data of a parameter variationexperiment with one variable parameter Mean service time and one scalar output

Utilization|Server utilization :

[ ["Mean service time", "Utilization|Server utilization"], [1.8, 0.5621987153519676], [1.9, 0.5939408971748594], [2, 0.6253419155200399]]

ModelRun classThe ModelRun class is responsible for communication with and control of a model run (withoutanimation) executed in Cloud. It can be considered as a frontend mirror of a backendexperiment run. Objects of class ModelRun are created and returned by calling the functionscreateSimulation() or createParameterVariation() of the CloudClient. A ModelRun objectcontains full information about the model, version, inputs, and experiment type.

run() - requests to run the experiment. Whether or not the simulation will actually be executeddepends on the availability of the outputs. The function returns the same ModelRun objectby Promise once the HTTP request completes; it does not wait for simulation completion oroutputs availability and does no polling.

stop() - requests to stop the model execution. Returns the same ModelRun object by Promiseonce the HTTP request completes.

waitForCompletion( pollingPeriod ) - waits for the experiment to complete and returns thesame ModelRun object by Promise. The pollingPeriod parameter is optional, the defaultvalue is 5000ms.

getStatus() - returns the status of the model execution as last updated by polling (does notinitiate any extra communication with the server). Possible values are the same asdescribed in the Experiment Run State section.

getProgress() - returns the fully parsed message field of the Experiment Run State object byPromise. To find out total experiment progress use getProgress().then( progress =>progress.total).

getOutputs( requiredOutputNames ) - if the run has already been completed, returns the runoutputs (either SingleRunOutputs or MultiRunOutputs object) by Promise, otherwise throws404 Error. requiredOutputNames is the array of output names that are to be returned. IfrequiredOutputNames is omitted, the behavior is different for single and multi-runexperiments: for a single run, all outputs are returned, for a multi run only outputs of scalartypes are returned.

getOutputsAndRunIfAbsent( requiredOutputNames, pollingPeriod ) - if the run has alreadybeen completed, returns the run outputs (either SingleRunOutputs or MultiRunOutputsobject) by Promise, otherwise requests to run the experiment, waits for completion bypolling, and then returns the outputs by Promise. requiredOutputNames has the samemeaning as in getOutputs(). The pollingPeriod parameter is optional, the default value is5000ms.

Animation classThe Animation class is responsible for communication with and control of an animatedsimulation run. Object of class Animation is created and returned by calling the functionsstartAnimation() of the CloudClient.

stop() - requests to stop the model execution. Does not return anything.

pause() - requests to pause the model execution. Returns the same Animation object byPromise.

resume() - requests to resume the (paused) model execution. Returns the same Animationobject by Promise.

setSpeed(speed) - requests to set the execution speed of the model to a given value (modeltime units per real second). Returns the same Animation object by Promise.

setVirtualTime() - requests to switch to the virtual time (fastest possible) execution mode.Returns the same Animation object by Promise.

navigateTo(viewArea) - requests to navigate to a view area with the given name. Returns thesame Animation object by Promise.

setPresentable(pathToPresentable) - requests to navigate to a given agent. The path shouldstart with experiment.root followed by Java path to the agent (if that is not root). Returnsthe same Animation object by Promise.

setValue(pathToField, value) - requests to set the value of a given object in the model (e.g.a parameter or a variable). The path to the object should look likeexperiment.root.agent1.myParameter. Returns the same Animation object by Promise.

getValue(pathToField) - requests the value of a given object in the model and returns it byPromise. The path to the object should look like experiment.root.agent1.myParameter. Thereturned value is a JavaScript object, please see Data conversion section to learn how Javaobjects are mapped to JSON objects.

getState() - requests the state of the animated model being executed and returns it byPromise. Please do not confuse the state of animated model with the status of the non-animated run that is returned by ModelRun.getStatus(). The returned value will be one of:

"IDLE"

"RUNNING"

"PAUSED"

"FINISHED"

"ERROR"

"PLEASE_WAIT"

"INITIALIZE"

"STOPPED"

"TIME_LIMIT"

"TERMINATED"

callFunction(pathToFunction, args) - requests to call a function in the model, possiblyproviding arguments. Returns what the function returns, by Promise. The path to thefunction should look like experiment.root.agent1.myFunction. args is a JavaScript array ofthe function argument objects, see Data conversion section to learn how Java objects aremapped to JSON objects.

waitForCompletion() - waits for animated simulation to complete and returns the sameAnimation object by Promise. Note that even if the simulation run has finished (has reachedthe stop time), it will not be considered as completed until the use presses Stop, or stop()method has been called, or the server terminates the simulation due to an error.

JavaScript API reference

4.3 Writing HTML and CSS for AnyLogic Cloud things tokeep in mindIf you are going to embed model animation in your web page, please make sure there is noCSS style and HTML id intersection between your part of the page and embedded AnyLogicanimation part. The CSS st

Documents

AnyLogic Cloud API 8.5.0 Documentation · 2020. 9. 4. · AnyLogic Cloud keeps the inputs and outputs of all the experiments that have been ever run with each model version. Model