Cloud Java API

Applies to AnyLogic Cloud 2.5.0. Last modified on November 20, 2024.

To start using the API

1. Download the client .jar package using the following link:

   https://cloud.anylogic.com/files/api-8.5.0/clients/anylogic-cloud-client-8.5.0.jar
   For Private Cloud 2.3.1 and older versions: https://cloud.anylogic.com/files/api-8.5.0/clients/anylogic-cloud-client-8.5.0-old.jar

   • Inside the folder containing your AnyLogic Cloud API Java project, create a new folder and name it libs.
   • Place the .jar package you have downloaded in the libs folder.
   • Open the build.gradle file that belongs to your project.
   • Add the following code to the file contents:

     repositories {
         mavenCentral()
         flatDir {
             dirs 'libs'
         }
     }
     dependencies {
         implementation group: 'com.anylogic.cloud.clients', name: 'anylogic-cloudclient', version: '8.5.0'
     }

   • Save the changes in the build.gradle file.
   • Perform a re-import of all Gradle projects in the Java IDE you use.
2. Obtain the API key in the AnyLogic Cloud UI.
3. Create a new instance of the CloudClient object:

   For public version of AnyLogic Cloud:

   String apiKey = "<the API key>";
   AnyLogicCloudClient client = new AnyLogicCloudClient( apiKey );

   For Private Cloud:

   String apiKey = "<the API key>";
   String host = "<the Cloud instance URL>";
   AnyLogicCloudClient client = new AnyLogicCloudClient( apiKey, host );

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

AnyLogic Java API is synchronous (see Synchronous and asynchronous API).

The API treats names (for example, model, experiment, input, and output names) as case-insensitive.

The AnyLogicCloudClient class is responsible for authentication and communication with the AnyLogic Cloud. Typically, there is only one object of class AnyLogicCloudClient in your Java code.

An object of Inputs class is constructed in preparation of a model run (of any kind) by calling the AnyLogicCloudClient functions createDefaultInputs() or createInputsFromExperiment() and contains full information about the model, model version, and the input values. It should not be confused with the inputs field in the Version object.

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

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

An 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 simplifies navigation within the complex outputs structure. Keep in mind that you need to explicitly specify the required outputs when calling getOutputs() functions.

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

The ModelRun class is responsible for communication with and control of a model run (without animation) executed in Cloud. It can be considered as a front-end mirror of a back-end experiment run.

Objects of ModelRun subclasses are created and returned by calling the functions createSimulation(), createParameterVariation(), createMonteCarloFirstOrder(), or createParameterVariationWithReplications() of the AnyLogicCloudClient. A ModelRun object contains full information about the model, version, inputs, and experiment type.

The SimulationRun subclass is used to communicate with with and control a simulation experiment (without animation) executed in Cloud. Objects of the SimulationRun subclass are created and returned by calling the createSimulation() function of the AnyLogicCloudClient.

The ParameterVariationRun subclass is used to communicate with and control a parameter variation experiment (without animation) executed in Cloud. Objects of the ParameterVariationRun class are created and returned by calling the createParameterVariation() and createParameterVariationWithReplications() functions of the AnyLogicCloudClient.

The MonteCarloFirstOrderRun subclass is used to communicate with and control a Monte Carlo 1^st Order experiment (without animation) executed in Cloud. Objects of the MonteCarloFirstOrderRun class are created and returned by calling the createMonteCarloFirstOrder() function of the AnyLogicCloudClient.

The following methods are common for all ModelRun objects:

Simulation run without animation (minimalistic)

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

String API_KEY = "e05a6efa-ea5f-4adf-b090-ae0ca7d16c20";
String DOUBLE_INPUT = "Server capacity";
String DOUBLE_OUTPUT = "Utilization|Server utilization";
AnyLogicCloudClient client = new AnyLogicCloudClient(API_KEY);
Model model = client.getModelByName("Service System Demo");
ModelVersion version = client.getLatestModelVersion(model);

Inputs inputs = client.createDefaultInputs(version);
inputs.setInput(DOUBLE_INPUT, 20);
SimulationRun simulation = client.createSimulation(inputs);
SingleRunOutputs outputs = simulation.getOutputsAndRunIfAbsent(); // will exit upon run completion

System.out.println(outputs.value(DOUBLE_OUTPUT));

First, we define 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 name (Service System Demo).
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 outputs
   • If such simulation has not been run yet, it runs the simulation and waits for the outputs. The SingleRunOutputs object is returned
8. Finally, the output value for the “Average performance” field is displayed in the Java console using the API of SingleRunOutputs.

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

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 information refer to the Output data object section. The case, however, does not matter: you can use either lower case or upper case.

Querying simulation results of a completed run

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

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 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));
      }
  }

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

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

Running parameter variation

In this example, we will run a parameter variation experiment. One of the input parameters will be a discrete range. To demonstrate one more feature of the AnyLogic Cloud API, we will take the input values from an existing simulation experiment defined in the standard AnyLogic Cloud web interface and change a parameter value from a scalar to a range.

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.*;

import java.util.Arrays;

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) {
        parameterVariationRun();
    }

    private static void parameterVariationRun() {
        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));
    }
}

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

Here, we use the Inputs.setRangeInput() function to change the value of the "Server capacity" input to a range type, from 20.0 to 180.0 with step 20.0. Therefore, nine simulation runs are to be performed.

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

The run of parameter variation is invoked by calling the getOutputsAndRunIfAbsent() function just like in our previous examples, but there is one important difference. Full outputs of a multiple run experiment may be a very large piece of data, so the API user has to explicitly specify which outputs need to be delivered. This is done by listing the output names in the array 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 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 a number of functions simplifying navigation.

Running parameter variation with replications

In this example, we will run a parameter variation experiment with the explicitly set number of replications. One of the input parameters will be varied in range. We will also use the input values from an existing simulation experiment defined in the standard AnyLogic Cloud web interface.

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.*;

import java.util.Arrays;

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) {
        parameterVariationWithReplicationsRun();
    }

    private static void parameterVariationWithReplicationsRun() {
        System.out.println( "A parameter variation with replications run with Double input varied from 20.0 to 180.0 with step 20.0, 4 replications" );
        AnyLogicCloudClient client = new AnyLogicCloudClient(API_KEY, HOST);
        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);
        inputs.setNumberOfReplications(4);
        ParameterVariationRun variation = client.createParameterVariationWithReplications(inputs);
        MultiRunOutputs outputs = variation.getOutputsAndRunIfAbsent(Arrays.asList(DOUBLE_OUTPUT)); // will exit upon run completion
        System.out.println(outputs.getValuesOfOutput(DOUBLE_OUTPUT));
    }
}

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

Here, we use the Inputs.setNumberOfReplications() function to specify the number of replications to be run.

Then we create a ModelRun object for the needed experiment type, which is done by the AnyLogicCloudClient.createParameterVariationWithReplications() function.

The experiment run is triggered by calling the getOutputsAndRunIfAbsent() function just like in our previous examples, but there is one important difference. Full outputs of a multiple run experiment may be a very large piece of data, so the API user has to explicitly specify which outputs need to be delivered. This is done by listing the output names in the array 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 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 a number of functions simplifying navigation.

Running Monte Carlo 1^st order

In this example, we will run a Monte Carlo 1^st order experiment with the explicitly set number of replications. When executed via the API, the Monte Carlo experiment runs the simulation a specified number of times, obtains the collections of values, and then returns them.

One of the input parameters will be a discrete range. We will also use the input values from an existing simulation experiment defined in the standard AnyLogic Cloud web interface.

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.*;

import java.util.Arrays;

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) {
        monteCarloFirstOrderRun();
    }

    private static void monteCarloFirstOrderRun() {
        System.out.println( "A Monte-Carlo 1st order run with 4 replications" );
        AnyLogicCloudClient client = new AnyLogicCloudClient(API_KEY, HOST);
        Model model = client.getModelById(MODEL_ID);
        ModelVersion version = client.getLatestModelVersion(model);
        Inputs inputs = client.createDefaultInputs(version);
        inputs.setNumberOfReplications(4);
        MonteCarloFirstOrderRun monteCarlo = client.createMonteCarloFirstOrder(inputs);
        MultiRunOutputs outputs = monteCarlo.getOutputsAndRunIfAbsent(Arrays.asList(DOUBLE_OUTPUT)); // will exit upon run completion
        System.out.println(outputs.getValuesOfOutput(DOUBLE_OUTPUT));
    }
}

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

The Inputs.setNumberOfReplications() function specifies the number of replications to be run.

Then we create a ModelRun object for the needed experiment type, which is done by the AnyLogicCloudClient.createMonteCarloFirstOrder() function.

The experiment run is triggered by calling the getOutputsAndRunIfAbsent() function just like in our previous examples, but there is one important difference. Full outputs of a multiple run experiment may be a very large piece of data, so the API user has to explicitly specify which outputs need to be delivered. This is done by listing the output names in the array 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 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 a number of functions simplifying navigation.

Using a file as an input and output

In this example, we will run a simple model that requires an input file. The model will write new values to this file. Then, we will download the file (by then it will contain new values) as output.

import com.anylogic.cloud.clients.client_8_5_0.*;
import com.anylogic.cloud.service.open_8_5_0.api.project.*;
import java.io.IOException;
import java.nio.file.Paths;
 
public static void main( String[] args ) throws IOException {
    System.out.println("Authorizing and uploading input file data.xlsx ...");
    AnyLogicCloudClient client = new AnyLogicCloudClient( "e05a6efa-ea5f-4adf-b090-ae0ca7d16c20", "https://cloud.anylogic.com");
    String inputFileHash = client.uploadFile( Paths.get( "data.xlsx" ) );
 
    System.out.println("Setting up simulation File IO API Demo ...");
    Model model = client.getModelByName("File IO API Demo");
    ModelVersion version = client.getLatestModelVersion(model);
    Inputs inputs = client.createDefaultInputs(version);
    inputs.setInput("Data", inputFileHash);
 
    System.out.println( "Running simulation...");
    SimulationRun simulation = client.createSimulation(inputs);
    SingleRunOutputs outputs = simulation.getOutputsAndRunIfAbsent();
 
    System.out.println( "Downloading data.xlsx file populated with output data...");
    String fileResource = outputs.value("Data");   
    client.downloadFile(fileResource);
 
    System.out.println( "Complete!");
}

First, we calculate the hash code from the file that is located in the file system on the machine we use to execute the experiment via the Java API, using the uploadFile() function. This is done with the help of the built-in Java Paths class, which converts the provided relative file path (a string) to the Path Java object.

Then, we specify the model (which in this case already is present in Cloud) and tell Cloud the file to use as input, using the calculated hash code.

When the experiment is completed, we first convert the resulting data to the unparsed JSON string. This string is handled by the AnyLogic Cloud API client, which accepts it as a parameter for the downloadFile() function.

How can we improve this article?

Send