v1.0.0 release

The long-awaited release of Alpyne v1.0.0 is here! This version is a dramatic overhaul of the library; it is not backwards compatible -- see the updated documentation and new example scripts for usage.

Install/Upgrade

For just the minimal dependencies, use: pip install --upgrade anylogic-alpyne

For the dependencies needed to run the examples, use: pip install --upgrade anylogic-alpyne[examples]

⚠️ To run the example scripts, you will first need to export the models from AnyLogic. See the examples' readme for detailed instruction.

Summary of major changes

• Minimum requirement of Python 3.10+ and AnyLogic 8.8.6+
• Complete rewrite of the backend server logic for improved stability
• Removes the similarity to AnyLogic Cloud's API, enabling a more streamlined and straight forward way to interact with your model
• Each instance of the AlpyneClient - now called "AnyLogicSim" - now creates and manages one (and only one!) instance of your model
• Separate logging and log level settings for the Python client (terminal output) and the underlying Java executable (alpyne.log and model.log)
• New and updated examples and use cases; the examples folder and individual examples each have their own READMEs

Detailed changes list

• The primary object now controls one and only one instance of the sim; its functions have been appropriately changed to directly interact with the run
• The primary object is named "AnyLogicSim" from "AlpyneClient"
• Add name/value-type validation before the request is sent to your model
• Implement conditional waiting logic (formally refereed to as "blocking", now "locking") server-side for higher response times
• Separated engine settings (for setting units, time/date, RNG seed) from the Configuration into its own type (EngineSettings)
• AnyLogicSim constructor arguments add support for separate Python/Java logging, logging IDs, default values for the Configuration, engine settings, and locking behaviors, and more
• Values are now set directly, rather than through custom "ModelData" objects
• The ModelData class (with name, type, value, and unit attributes) is renamed to FieldData
• The ModelVersion class (with lists of formally-ModelData objects for each input, output and space type) is renamed to SimSchema
• Configuration, Observation, and Action objects are now dictionary-subclasses rather than a novel class type
• Actionable functions (i.e., reseting, taking action) now accept keyword arguments of the space's values, rather than requiring an instance of the relevant space type
• Add the SimStatus class - queryable on-the-fly or as the return of certain requests - which contains most relevant information about the sim, including the engine state, observation, stop condition value, counters, time/date
• Add the EngineStatus class; works similarly to SimStatus and contains detailed information about the engine (e.g., state, event counter, start/stop settings)
• The enum attribute describing an indication of the current run has been changed: previously called "status" and had novel definitions; now called "state" and is based directly on the state enum of the AnyLogic Engine (re-implemented in Python in the EngineState class)
• The EngineState enum inherits from Flag, enabling bitwise operations (e.g., EngineState.FINISHED|EngineState.PAUSED)
• Removed support for setting values as tuples ((start, stop, step)); supports for constants or zero-argument functions still exist
• Usage of Farama's Gymnasium instead of OpenAI's Gym
• Overhaul to the provided abstract RL environment
• Implementation of classes for each output type (e.g., HistogramData, DataSet, Output), including a custom type for values with units (UnitValue), and enums for each unit type, including functions for unit conversion (similar to how it works in AnyLogic); these values are retrievable by the outputs function
• Improved stability and checks involved in both the startup and shutdown process
• Re-organization of the library's file structure - flattened directories, renamed file names, added new files