- Справочник API
- Примеры
- «Прогон» эксперимента без анимации (простой)
- Запрос результатов эксперимента завершенного «прогона»
- «Прогон» эксперимента с опросом о ходе выполнения
- Запуск нестандартного потока операций
- Запуск эксперимента варьирования параметров
- Запуск варьирования параметров с репликациями
- Запуск Монте-Карло 1-го порядка
Обновлено 04.12.2024
Чтобы использовать Python API, выполните следующие действия:
-
Установите клиентскую библиотеку AnyLogic Cloud с помощью установщика пакетов pip:
pip install https://cloud.anylogic.com/files/api-8.5.0/clients/anylogiccloudclient-8.5.0-py3-none-any.whl
Для Private Cloud 2.3.1 и предыдущих версий: pip install https://cloud.anylogic.com/files/api-8.5.0/clients/anylogiccloudclient-8.5.0-py3-none-any-old.whl -
Убедитесь, что установка пакета успешно завершена:
Если не возникло ошибок, вы можете использовать API для работы с моделями Cloud.$ python >>> import anylogiccloudclient.client.cloud_client
Вы также можете установить пакет вручную. Для загрузки пакета пройдите по ссылке:
https://cloud.anylogic.com/files/api-8.5.0/clients/anylogiccloudclient-8.5.0.tar.gz
Для Private Cloud 2.3.1 и предыдущих версий: https://cloud.anylogic.com/files/api-8.5.0/clients/anylogiccloudclient-8.5.0-old.tar.gz
При ручной установке убедитесь, что значение переменной PYTHONPATH указывает на местоположение клиентской библиотеки AnyLogic Cloud перед ее использованием.
AnyLogic Python API является синхронным (см. Синхронный и асинхронный API).
Напомним, что API обрабатывает имена (например, модели, эксперимента, входных и выходных данных) как нечувствительные к регистру.
Класс CloudClient отвечает за аутентификацию и взаимодействие с AnyLogic Cloud. Как правило, в коде Python может быть только один экземпляр класса CloudClient.
Функция | Описание |
---|---|
get_models() | Возвращает доступные модели в виде массива объектов Model. |
get_model_by_id(id) | Возвращает объект Model с заданным идентификатором id. |
get_model_by_name(name) | Возвращает объект Model с заданным именем name. |
get_model_version_by_id(model, version_id) | Возвращает объект Version заданного объекта Model с заданным идентификатором version_id. |
get_model_version_by_number(model, version_number) | Возвращает объект Version данного объекта Model с заданным номером version_number. Нумерация версий начинается с 1. |
get_latest_model_version(model) | Возвращает объект Version (последняя версия) заданной модели model (может быть объектом Model или именем модели). |
create_default_inputs(version) | Создает и возвращает объект Inputs для объекта Version заданной модели с входными значениями по умолчанию. |
create_inputs_from_experiment(version, experiment_name) | Создает и возвращает объект Inputs для объекта Version заданной модели, скопированного из эксперимента с заданным именем experiment_name. |
create_simulation(inputs) | Создает и возвращает объект ModelRun типа SIMULATION с заданным значением объекта Inputs (модель и версия идентифицируются по входным данным — inputs). |
create_parameter_variation(inputs) | Создает и возвращает объект ModelRun типа PARAMETER_VARIATION с заданным значением Inputs (модель, ее версия и диапазон входных данных идентифицируются по входным данным — inputs). |
create_monte_carlo(inputs) | Создает и возвращает объект ModelRun типа MONTE_CARLO с заданным значением Inputs (модель и версия идентифицируются по inputs). |
create_parameter_variation_with_replication(inputs) | Создает и возвращает объект ModelRun типа PARAMETER_VARIATION_WITH_REPLICATIONS с заданными значением Inputs (модель, ее версия, входной диапазон и количество репликаций идентифицируются по inputs). |
Объект класса Inputs создается при подготовке к запуску модели (любого типа) путем вызова функций CloudClient: create_default_inputs() или create_inputs_from_experiment(). Он содержит всю информацию о модели, версии модели и входных данных. Не путайте этот класс с полем inputs объекта Version.
Функция | Описание |
---|---|
get_input(name) | Возвращает значение элемента входных данных с заданным именем name. Возможные типы см. в разделе Преобразование данных. |
set_input(name, value) | Устанавливает значение элемента входных данных с заданным именем name. |
set_range_input(name, min, max, step) | Устанавливает диапазон для входных данных с заданным именем (в эксперименте с варьированием параметров или варьирование параметров с репликациями). |
names(self) | Возвращает список имен всех элементов входных данных. |
set_number_of_replications(num) | Устанавливает число репликаций для эксперимента с варьированием параметров. Значение по умолчанию — 3. |
Входные данные типа распределения (для экспериментов Монте-Карло второго порядка) появятся в будущих версиях AnyLogic Cloud API.
Объект этого класса возвращается после вызова функций get_outputs() или get_outputs_and_run_if_absent() объекта ModelRun, созданного для простого эксперимента с одним «прогоном».
Функция | Описание |
---|---|
names() | Возвращает массив со всеми именами элементов выходных данных. |
find_name_including(name_part) | Ищет имя элемента выходных данных, содержащее name_part в качестве подстроки, и возвращает его. Если такого имени нет или найдено более одного имени, выдает ошибку. Эта функция нужна, так как полные имена выходных данных могут быть составными: см. Объект "Выходные данные. |
value(name) | Возвращает значение элемента выходных данных с заданным именем. Тип значения зависит от типа выходных данных: см. Преобразование данных. |
get_raw_outputs() |
Возвращает массив всех элементов выходных данных. Каждый элемент имеет следующие поля: name, type, units, value. Возможные значения полей type и units см. в разделах Типы выходных данных и Единицы измерения соответственно. Поле значения содержит объект, созданный, как описано в разделе Преобразование данных.
|
Объект этого класса возвращается после вызова функций get_outputs() или get_outputs_and_run_if_absent() объекта ModelRun, созданного для эксперимента с варьированием параметров или другого эксперимента с несколькими прогонами. Это упрощает навигацию по сложной структуре выходных данных.
Функция | Описание |
---|---|
get_input_names() | Возвращает массив имен элементов входных данных, различающихся для разных прогонов. |
get_output_names() | Возвращает массив имен запрошенных элементов выходных данных. |
get_values_of_input( name ) |
Возвращает массив значений входных данных с заданным именем для всех прогонов в некоторой фиксированной последовательности.
Вы можете получить значения только варьирующихся входных данных. Фиксированные входные данные не хранятся в классе MultiRunOutputs.
|
get_values_of_output( name ) | Возвращает массив значений выходных данных с заданным именем для всех прогонов в некоторой фиксированной последовательности. Эту функцию можно использовать вместе с get_values_of_input(). |
get_raw_data() |
Возвращает таблицу (двумерный массив) со значениями всех переменных входных данных и всех выходных данных со строкой заголовка.
|
Класс ModelRun отвечает за обмен информацией во время прогона модели и контролирует этот прогон (без анимации, в Cloud). По сути, это внешний интерфейс внутренних процессов прогона эксперимента. Объекты класса ModelRun создаются и возвращаются путем вызова функций create_simulation(), create_parameter_variation(), create_monte_carlo() или create_parameter_variation_with_replications() класса CloudClient. Объект ModelRun содержит всю информацию о модели, версии, входных данных и типе эксперимента.
Функция | Описание |
---|---|
run() | Запрашивает запуск эксперимента. О фактическом выполнении эксперимента говорит наличие выходных данных. Функция возвращает тот же объект ModelRun после завершения HTTP-запроса; она не ожидает завершения эксперимента или появления выходных данных и не отсылает дополнительных запросов. |
stop() | Запрашивает остановку выполнения модели. Возвращает тот же объект ModelRun после завершения HTTP-запроса. |
wait_for_completion(polling_period) | Ожидает завершения эксперимента и возвращает тот же объект ModelRun. Параметр polling_period является необязательным. Значение по умолчанию: 5000ms. |
get_status() | Возвращает статус выполнения модели, который последний раз обновлялся с помощью опроса (не инициирует дополнительную связь с сервером). Возможные значения такие же, как описано в разделе Статус прогона эксперимента. |
get_progress() | Возвращает полностью обработанное поле message объекта Experiment Run State. Чтобы узнать о ходе выполнения эксперимента, используйте get_progress()["total"]. |
get_outputs(required_output_names) |
Если «прогон» уже завершен, возвращает выходные данные «прогона» (либо объект SingleRunOutputs, либо объект MultiRunOutputs), в противном случае выдает ошибку 404. Параметр required_output_names — это массив возвращаемых выходных имен. Если required_output_names опущен, поведение экспериментов с одним и несколькими прогонами отличается: для одного «прогона» возвращаются все выходные данные, для многократного «прогона» возвращаются только выходные данные скалярных типов. |
get_outputs_and_run_if_absent(required_output_names, polling_period) | Если «прогон» уже завершен, возвращает выходные данные «прогона» (либо объект SingleRunOutputs, либо объект MultiRunOutputs), в противном случае запрашивает запуск эксперимента, ожидает завершения, делая опрос, а затем возвращает выходные данные. required_output_names имеет такое же значение, как и для функции get_outputs(). Параметр polling_period необязателен. Значение по умолчанию: 5000ms. |
«Прогон» эксперимента без анимации (простой)
-
Используйте API функцию ModelRun.get_outputs_and_run_if_absent().
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 считается бэкенд (back-end) языком программирования, поэтому входные и выходные данные доступны только через консоль:
- С помощью ключа API создается объект CloudClient.
- Сервер ищет последнюю версию модели с именем "Service System Demo".
- Когда (и если) такая модель и версия найдены, мы создаем объект Inputs с входными данными по умолчанию.
- Используем функцию set_input(), чтобы изменить значение параметра "Server capacity" на 8.
- Далее запрашиваем CloudClient создать объект simulation с входными данными. Это делается на стороне клиента, коммуникации с сервером нет.
-
Вызывается функция getOutputsAndRunIfAbsent(), которая проверяет статус эксперимента:
- Если этот эксперимент завершен, функция возвращает выходные данные
- Если эксперимент еще не запускался, эта функция запускает его и ожидает получения выходных данных.
- Наконец, полученные выходные значения и соответствующие входные данные отображаются в консоли с помощью API SingleRunOutputs и Inputs.
Если на каком-либо шаге произойдет ошибка, в консоли отобразится сообщение об ошибке.
Чтобы получить значение конкретных выходных данных, нужно указать имя этих данных именно так, как оно обозначено при загрузке модели в Cloud (подробнее см. в разделе об объекте Output. Регистр не учитывается: можно использовать и нижний, и верхний регистры. Запрос результатов эксперимента завершенного «прогона»
-
Здесь используется ключевая функция ModelRun.get_outputs().
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")))
-
Мы используем функцию set_input(), чтобы изменить значение параметра “Server capacity” на 8. Создав объекты inputs и simulation, мы вызываем simulation.get_outputs(). Если выходные данные существуют, они возвращаются. Если их нет, возникает ошибка.
«Прогон» эксперимента с опросом о ходе выполнения
-
В этом примере мы используем функцию ModelRun.get_progress() для получения информации о ходе выполнения эксперимента. Существует также другой способ запуска эксперимента и получения результатов: последовательный вызов функций: run(), wait_for_completion() и get_outputs().
import threading import 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")))
-
При стандартном создании входных данных мы увеличиваем значение системных входных данных {STOP_TIME}, чтобы иметь возможность следить за ходом выполнения эксперимента с увеличенной продолжительностью. Эти входные данные есть в каждой модели, загруженной в Cloud. Однако если прогон с таким же временем остановки и другими входными данными уже был выполнен, эксперимент не запустится, а выходные данные будут получены почти мгновенно. Таким образом, чтобы следить за ходом выполнения, попробуйте установить другие значения для входных данных.
Мы используем функцию progress_thread.start(), которая вызывается после simulation.run(). Она инициирует повторный вызов функции s.get_progress(), которая возвращает информацию о ходе выполнения. Для прогона простого эксперимента нас интересует только поле total. Для экспериментов с несколькими прогонами оно содержит больше деталей. Функция time.sleep() вызывается после завершения эксперимента. Она ждет еще 5 секунд, чтобы убедиться, что получено окончательное значение прогресса.
Вызов simulation.run() инициирует запуск эксперимента (только если эксперимент не запускался ранее) и возвращает тот же объект simulation. Она не ждет завершения эксперимента. Чтобы дождаться завершения эксперимента, мы используем функцию simulation.wait_for_completion(), которая также возвращает тот же объект. Только теперь мы запрашиваем результаты эксперимента, вызывая функцию simulation.get_outputs(). Эта последовательность здесь исключительно для демонстрационных целей. Ее можно заменить одним вызовом simulation.get_outputs_and_run_if_absent().
Запуск нестандартного потока операций
-
В этом примере показан нестандартный поток операций, в котором некоторые эксперименты выполняются параллельно, а некоторые — последовательно, на основе результатов других экспериментов. Этот сценарий может быть интересен тем, кто, например, планирует настроить алгоритм оптимизации в AnyLogic Cloud.
from anylogiccloudclient.client.cloud_client import CloudClient 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")))
-
В этом сценарии мы с помощью функции range() сначала выполняем параллельно два прогона эксперимента с параметром Server Capacity, равным 4 в одном прогоне и 9 в другом. Два запуска инициируются вызовом s.run().
Выходные данные параллельных прогонов эксперимента возвращаются в виде массива в том же порядке.
Когда вы параллельно запускаете несколько экспериментов вручную, как в этом примере, каждый вызов s.wait_for_completion() выполняет свой собственный независимый опрос. Много параллельных запусков могут привести к высокому HTTP-трафику. Если есть такие опасения, попробуйте изменить значение параметра polling_period этих функций. Запуск эксперимента варьирования параметров
-
В этом примере показано, как запустить эксперимент варьирования параметров. Один из входных параметров будет варьироваться в дискретном диапазоне. Чтобы продемонстрировать еще одну функцию AnyLogic Cloud API, возьмем входные значения существующего простого эксперимента из AnyLogic Cloud и изменим значение параметра со скалярного на диапазон.
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_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")))
-
Чтобы повторно использовать набор входных данных из эксперимента в AnyLogic Cloud, мы используем функцию CloudClient.create_inputs_from_experiment() вместо create_default_inputs(). Скопировав входные данные эксперимента Baseline, мы изменяем входные данные Mean service time на диапазонный тип (от 1,8 до 2,0 с шагом 0,1), вызвав функцию Inputs.set_range_input(). Таким образом, будет выполнено три прогона эксперимента.
Затем нужно создать объект ModelRun типа вариации параметров. Для этого мы выполняем функцию CloudClient.create_parameter_variation().
Запуск эксперимента с вариацией параметров вызывается функцией get_outputs_and_run_if_absent() точно так же, как и в предыдущих примерах, но есть одно важное отличие. Все выходные данные экспериментов с несколькими «прогонами» могут представлять собой очень большой фрагмент данных, поэтому пользователь API должен четко указать, какие выходные данные нужны. Для этого нужно указать в качестве параметра имена выходных данных в массиве в функциях get_outputs_and_run_if_absent() или get_outputs(). В этом примере показаны выходные данные Mean queue size|Mean queue size. Если параметр не указан для эксперимента с несколькими «прогонами», возвращаются только скалярные выходные данные, если таковые имеются.
Результаты эксперимента с несколькими «прогонами» возвращаются в виде объекта MultiRunOutputs, который имеет ряд функций, упрощающих навигацию.
Запуск варьирования параметров с репликациями
-
В данном примере представлен запуск эксперимента варьирования параметров с четко заданным количеством репликаций. Один из входных параметров будет варьироваться в диапазоне. Также мы будем использовать входные значения реально существующего простого эксперимента в AnyLogic Cloud.
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_range_input("Mean service time", 1.8, 2, 0.1) inputs.set_number_of_replications(4) variation_with_replications = client.create_parameter_variation_with_replications(inputs) outputs = variation_with_replications.get_outputs_and_run_if_absent(["Total time in system|Total time in system"]) print("Parameter variation with replications experiment completed") invalues = outputs.get_values_of_input("Mean service time") outvalues = outputs.get_values_of_output("Total time in system|Total time in system") for i in range(len(invalues)): print("When Mean service time = " + str(invalues[i]) + ", mean Total time in system = " + str(outvalues[i]["statistics"]["mean"]))
-
Как видите, этот эксперимент по большей части не отличается от приведенного примера с вариацией параметров. Основное отличие состоит в том, что мы используем функцию set_number_of_replications() для четкого указания количества репликаций.
Затем с помощью функции CloudClient.create_parameter_variation_with_replications() мы создаем объект ModelRun для нужного типа эксперимента.
«Прогон» эксперимента запускается вызовом функции get_outputs_and_run_if_absent() точно так же, как и в предыдущих примерах, но есть одно важное отличие. Все выходные данные экспериментов с несколькими «прогонами» могут представлять собой очень большой фрагмент данных, поэтому пользователь API должен четко указать, какие выходные данные нужны. Для этого нужно указать в качестве параметра имена выходных данных в массиве в функциях get_outputs_and_run_if_absent() или get_outputs(). В этом примере показаны выходные данные Total time in system | Total time in system. Если параметр не указан для эксперимента с несколькими прогонами, возвращаются только скалярные выходные данные, если таковые имеются.
Результаты эксперимента с несколькими прогонами возвращаются в виде объекта MultiRunOutputs, который имеет ряд функций, упрощающих навигацию.
-
Запуск Монте-Карло 1-го порядка
-
В данном примере запустим эксперимент Монте-Карло 1-го порядка с четко заданным количеством репликаций. При выполнении через API эксперимент Монте-Карло запускается заданное количество раз, получает наборы значений, а затем возвращает их.
Один из входных параметров будет варьироваться в диапазоне. Мы также будем использовать входные значения из существующего простого эксперимента AnyLogic Cloud.
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_number_of_replications(4) monte_carlo = client.create_monte_carlo(inputs) outputs = monte_carlo.get_outputs_and_run_if_absent(["Total time in system|Total time in system"]) print("Monte Carlo 1st order experiment completed") invalues = outputs.get_values_of_input("Mean service time") outvalues = outputs.get_values_of_output("Total time in system|Total time in system") for i in range(len(invalues)): print("When Mean service time = " + str(invalues[i]) + ", mean Total time in system = " + str(outvalues[i]["statistics"]["mean"]))
-
Мы повторно используем набор входных данных из эксперимента, находящегося в AnyLogic Cloud, с помощью функции create_inputs_from_experiment(). Количество репликаций задается с помощью функции set_number_of_replications().
Затем мы создаем объект ModelRun для нужного типа эксперимента с помощью функции CloudClient.create_monte_carlo().
Прогон эксперимента запускается вызовом функции get_outputs_and_run_if_absent() точно так же, как и в предыдущих примерах, но есть одно важное отличие. Все выходные данные экспериментов с несколькими прогонами могут представлять собой очень большой фрагмент данных, поэтому пользователь API должен четко указать, какие выходные данные нужны. Для этого нужно указать в качестве параметра имена выходных данных в массиве в функциях get_outputs_and_run_if_absent() или get_outputs(). В этом примере показаны выходные данные Total time in system | Total time in system. Если параметр не указан для эксперимента с несколькими прогонами, возвращаются только скалярные выходные данные, если таковые имеются.
Выходные данные эксперимента с несколькими прогонами возвращаются в виде объекта MultiRunOutputs, который имеет ряд функций, упрощающих навигацию.
-
Как мы можем улучшить эту статью?
-