Cloud Java API

Обновлено 09.12.2024

Чтобы начать использовать Java API:

1. Скачайте .jar-пакет API-клиента по следующей ссылке:
   

   https://cloud.anylogic.com/files/api-8.5.0/clients/anylogic-cloud-client-8.5.0.jar
   Для Private Cloud 2.3.1 и предыдущих версий: https://cloud.anylogic.com/files/api-8.5.0/clients/anylogic-cloud-client-8.5.0-old.jar

2. Создайте новую директорию внутри директории вашего Java API-проекта. Назовите ее libs.
3. Поместите загруженный .jar-пакет внутрь директории libs.
4. Откройте файл build.gradle вашего проекта.
5. Добавьте внутрь файла следующий код:

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

6. Сохраните изменения в файле build.gradle.
7. Повторно импортируйте все Gradle-проекты изнутри вашей среды разработки Java.
8. Используйте API для работы с моделями в Cloud.

Java API AnyLogic является синхронным (см. раздел Синхронный и асинхронный API).

Java API считает имена объектов нечувствительными к регистру. Это относится к именам моделей, экспериментов, входных и выходных данных.

Класс AnyLogicCloudClient отвечает за аутентификацию и взаимодействие с AnyLogic Cloud. Обычно в рамках одной большой задачи в Java-коде требуется только один экземпляр класса AnyLogicCloudClient.

Объект класса Inputs создается перед любым «прогоном» модели путем вызова одной из функций AnyLogicCloudClient: createDefaultInputs() или createInputsFromExperiment(). Внутри объекта хранится вся информация о модели, версии и значениях входных данных. Не следует путать этот объект с полем inputs у объекта типа Version.

Элементы входных данных для значений распределения (например, экспериментов Монте-Карло второго порядка) появятся в следующих релизах AnyLogic Cloud API.

Объект этого класса возвращается после вызова функций getOutputs() или getOutputsAndRunIfAbsent() объекта ModelRun, который конструируется при создании простого эксперимента.

Объект этого класса возвращается при вызове функций getOutputs() и getOutputsAndRunIfAbsent() объекта ModelRun, созданного для эксперимента варьирования параметров или другого эксперимента, требующего более одного «прогона» модели. С помощью этого объекта можно анализировать содержимое множества элементов выходных данных. Обратите внимание, что при вызове getOutputs() нужные элемент выходных данных следует указывать явно.

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

Класс ModelRun отвечает за взаимодействие и управление «прогоном» модели, выполненным в Cloud, без учета анимации, — это своего рода «фронтенд» эксперимента.

Объекты подклассов ModelRun создаются и вызываются функциями createSimulation(), createParameterVariation(), createMonteCarloFirstOrder() и createParameterVariationWithReplications() объекта AnyLogicCloudClient. Объект ModelRun содержит полную информацию о модели, версии, входных данных и типе эксперимента.

Подкласс SimulationRun используется для взаимодействия и управления простым экспериментом (без анимации), выполненным в Cloud. Объекты подкласса SimulationRun создаются и возвращаются функцией createSimulation() объекта AnyLogicCloudClient.

Подкласс ParameterVariationRun используется для взаимодействия и управления экспериментом варьирования параметров (без анимации), выполненным в Cloud. Объекты класса ParameterVariationRun создаются и возвращаются функциями createParameterVariation() и createParameterVariationWithReplications() объекта AnyLogicCloudClient.

Подкласс MonteCarloFirstOrderRun используется для взаимодействия и управления экспериментом Монте-Карло первого порядка (без анимации), выполненным в Cloud. Объекты класса MonteCarloFirstOrderRun создаются и возвращаются функцией createMonteCarloFirstOrder() объекта AnyLogicCloudClient.

Следующие функции являются общими для всех объектов типа ModelRun:

Простой эксперимент без анимации (минималистичный)

Такой эксперимент запускается с помощью функции API 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(); // отключит соединение при окончании «прогона»

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

Сначала мы задаем несколько значений для элементов входных данных.

1. Конструируется экземпляр класса AnyLogicCloudClient. Для этого используется API-ключ.
2. На сервер отправляется запрос поиска модели с заданным именем (Service System Demo).
3. На сервер отправляется запрос поиска последней версии модели.
4. Когда (и если) модель и версия найдены, мы создаем объект Inputs со стандартными значениями входных данных.
5. Мы используем функцию setInput, чтобы изменить значение параметра Server capacity на 20.0. Остальные элементы входных данных сохранят значения по умолчанию.
6. Мы используем клиент AnyLogicCloudClient, чтобы создать объект simulation с элементами входных данных. Эта процедура осуществляется со стороны клиента; взаимодействие с сервером в этот момент не производится.
7. Вызывается функция getOutputsAndRunIfAbsent(), которая проверяет статус эксперимента:
   • Если эксперимент был завершен, функция возвращает выходные данные;
   • Если эксперимент еще не был запущен, функция запускает его и ожидает результатов.
   В обоих случаях возвращается объект типа SingleRunOutputs.
8. Наконец, мы получаем значение поля выходных данных Average performance и выводим его в консоли Java, используя API объекта SingleRunOutputs.

При появлении ошибки на любом из этих этапов, сообщение об этой ошибке появится в консоли Java.

Чтобы получить значение определенного элемента выходных данных, необходимо указать его имя в точности так же, как оно было указано при загрузке модели в Cloud (больше информации — в разделе об объекте Outputs). Данное имя, тем не менее, нечувствительно к регистру: вы можете использовать любой.

Запрос результатов завершенного эксперимента

Ключевая функция для этой задачи — 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));
      }
  }

Класс Example содержит несколько значений, которые мы используем для запроса.

Функция setInput() позволяет изменить значение параметра Server capacity на 20.0. Создав объекты inputs и simulation objects, мы вызываем функцию simulation.getOutputs(). Если выходные данные существуют, функция вернет их. При отсутствии соответствующих данных появится ошибка.

Запуск эксперимента варьирования параметров

В этом примере мы запустим эксперимент варьирования параметров, в котором значение одного из параметров будет варьироваться в пределах дискретного диапазона. Кроме того, чтобы продемонстрировать еще одну возможность AnyLogic Cloud API, мы возьмем значения для элементов входных данных из уже существующего простого эксперимента, созданного с помощью веб-интерфейса AnyLogic Cloud. После этого мы изменим значение одного из параметров со скалярного на диапазон.

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

Класс Example содержит несколько значений, которые мы используем для запроса.

Мы используем функцию Inputs.setRangeInput() чтобы изменить тип элемента входных данных Server capacity на диапазон от 20.0 до 180.0 с шагом 20.0. Таким образом, будут запущены 9 «прогонов».

Затем мы создаем объект ModelRun для варьирования параметров. Для этого используется функция AnyLogicCloudClient.createParameterVariation().

Запуск эксперимента осуществляется путем вызова функции getOutputsAndRunIfAbsent() так же, как и в одном из предыдущих экспериментов. Есть одно существенное отличие: полная выгрузка выходных данных эксперимента с несколькими «прогонами» модели может быть очень большой, так что пользователю API следует явно указать, какие выходные данные необходимо извлечь. Для этого можно заключить имена нужных элементов выходных данных в массиве, который передается аргументом функции getOutputsAndRunIfAbsent() или getOutputs(). В данном примере нас интересует элемент выходных данных, который называется Average performance. Если не передавать параметр с нужными элементами выходных данных, то функции, запрашивающие выходные данные, будут возвращать только скалярные значения (если они есть).

Выходные данные эксперимента с несколькими «прогонами» возвращаются в виде объекта MultiRunOutputs. Для этого объекта есть функции, упрощающие навигацию по нему.

Запуск эксперимента варьирования параметров с репликациями

В этом примере мы запустим эксперимент варьирования параметров с явно заданным числом репликаций. Значение одного из параметров будет варьироваться в пределах дискретного диапазона. Кроме того, мы извлечем значения для входных данных из существующего простого эксперимента, созданного через веб-интерфейс AnyLogic Cloud.

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

Класс Example содержит несколько значений, которые мы используем для запроса.

Мы используем функцию Inputs.setNumberOfReplications(), чтобы задать нужное число репликаций.

Затем мы создаем объект ModelRun для нужного типа эксперимента. Для этого используется функция AnyLogicCloudClient.createParameterVariationWithReplications().

Запуск эксперимента осуществляется путем вызова функции getOutputsAndRunIfAbsent() так же, как и в одном из предыдущих экспериментов. Есть одно существенное отличие: полная выгрузка выходных данных эксперимента с несколькими «прогонами» модели может быть очень большой, так что пользователю API следует явно указать, какие выходные данные необходимо извлечь. Для этого можно заключить имена нужных элементов выходных данных в массиве, который передается аргументом функции getOutputsAndRunIfAbsent() или getOutputs(). В данном примере нас интересует элемент выходных данных, который называется Average performance. Если не передавать параметр с нужными элементами выходных данных, то функции, запрашивающие выходные данные, будут возвращать только скалярные значения (если они есть).

Выходные данные эксперимента с несколькими «прогонами» возвращаются в виде объекта MultiRunOutputs. Для этого объекта есть функции, упрощающие навигацию по нему.

Запуск эксперимента Монте-Карло первого порядка

В этом примере мы запустим эксперимент Монте-Карло первого порядка с явно заданным числом репликаций. При запуске через API эксперимент Монте-Карло запускает «прогон» заданное число раз, получает список значений и возвращает их.

Значение одного из параметров будет варьироваться в пределах дискретного диапазона. Кроме того, мы извлечем значения для входных данных из существующего простого эксперимента, созданного через веб-интерфейс AnyLogic Cloud.

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

Класс Example содержит несколько значений, которые мы используем для запроса.

Мы используем функцию Inputs.setNumberOfReplications(), чтобы задать нужное число репликаций.

Затем мы создаем объект ModelRun для нужного типа эксперимента. Для этого используется функция AnyLogicCloudClient.createMonteCarloFirstOrder().

Запуск эксперимента осуществляется путем вызова функции getOutputsAndRunIfAbsent() так же, как и в одном из предыдущих экспериментов. Есть одно существенное отличие: полная выгрузка выходных данных эксперимента с несколькими «прогонами» модели может быть очень большой, так что пользователю API следует явно указать, какие выходные данные необходимо извлечь. Для этого можно заключить имена нужных элементов выходных данных в массиве, который передается аргументом функции getOutputsAndRunIfAbsent() или getOutputs(). В данном примере нас интересует элемент выходных данных, который называется Average performance. Если не передавать параметр с нужными элементами выходных данных, то функции, запрашивающие выходные данные, будут возвращать только скалярные значения (если они есть).

Выходные данные эксперимента с несколькими «прогонами» возвращаются в виде объекта MultiRunOutputs. Для этого объекта есть функции, упрощающие навигацию по нему.

Как мы можем улучшить эту статью?

Отправить