Metadata-Version: 2.4
Name: simulatr
Version: 0.1.0
Summary: Gym environment for reinforcement learning using ApsimX
Author-email: Meagan Lang <langmm.astro@gmail.com>
Maintainer-email: Meagan Lang <langmm.astro@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/langmm/simulatr
Project-URL: Documentation, https://github.com/langmm/simulatr
Project-URL: Repository, https://github.com/langmm/simulatr
Project-URL: Issues, https://github.com/langmm/simulatr/issues
Project-URL: Changelog, https://github.com/langmm/simulatr/blob/main/CHANGELOG.md
Keywords: apsim,apsimx,simulatr,reinforcement leanring,machine learning
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: fastapi
Requires-Dist: gymnasium
Requires-Dist: msgpack
Requires-Dist: numpy>=1.13.0
Requires-Dist: pandas
Requires-Dist: psutil
Requires-Dist: pydantic
Requires-Dist: pydantic-settings
Requires-Dist: pyzmq
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: git-changelog; extra == "dev"
Requires-Dist: myst-parser; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: tox; extra == "dev"
Dynamic: license-file

# Simulatr

[![PyPI version](https://img.shields.io/pypi/v/simulatr.svg)](https://pypi.org/project/simulatr/)
[![Python versions](https://img.shields.io/pypi/pyversions/simulatr.svg)](https://pypi.org/project/simulatr/)
[![PyPI downloads](https://img.shields.io/pypi/dm/simulatr.svg)](https://pypi.org/project/simulatr/)
[![License](https://img.shields.io/pypi/l/simulatr.svg)](https://github.com/langmm/simulatr/blob/main/LICENSE.txt)
[![Tests](https://github.com/langmm/simulatr/actions/workflows/runtests.yml/badge.svg)](https://github.com/langmm/simulatr/actions/workflows/runtests.yml)
[![Conda build](https://github.com/langmm/simulatr/actions/workflows/build-conda.yml/badge.svg)](https://github.com/langmm/simulatr/actions/workflows/build-conda.yml)
[![Docs](https://github.com/langmm/simulatr/actions/workflows/publish-docs.yml/badge.svg)](https://langmm.github.io/simulatr/)

Simulatr provides a [gymnasium](https://gymnasium.farama.org/) environment for reinforcement learning using different simulators including:

- [ApsimX](https://docs.apsim.info/)

# Installation

Simulatr can be installed via pip or pixi can be utilized

```
pip install -e .
```

In addition to installing the gym, you will also need to install the simulators you wish to run.

# Simulator installation

Simulatr will install the required simulators automatically, but you can also install the simulators yourself via the simulatr CLI before running a simulator

```
python -m simulatr install
```

# Running a simulator

## Running to completion

```
python -m simulatr run apsimx --crop-name wheat --from-example
```

## Running interactively

```
python -m simulatr run apsimx --crop-name wheat --from-example --timestep=10  # days
```

Additional documentation can be found [here](https://langmm.github.io/simulatr/),

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

<!-- insertion marker -->
## [v0.1.0](https://github.com/langmm/simulatr/releases/tag/v0.1.0) - 2026-08-20

<small>[Compare with v0.0.1](https://github.com/langmm/simulatr/compare/v0.0.1...v0.1.0)</small>

### Features

- Tools for hosting simulator engines as fastapi applications on beam
- Tools for creating n8n tools for simulator engine applications
- CLI for managine simulator applications and n8n tools
- Support for soil file input to crop models
- Utilities for iterating over pydantic fields that checks for annotations that should be skipped (used for n8n forms and CLI)
- Ability to create ApsimX models piecewise from components

### Added

- Added flag to prevent hang on apsimx termination due to failed connection ([27da4bf](https://github.com/langmm/simulatr/commit/27da4bfea8163c0aa478c7940ca5dd9c4c236a8b) by Meagan Lang).
- Added option to force reinstallation of simulator ([0f6846c](https://github.com/langmm/simulatr/commit/0f6846cfed36623406c88e51b119e5907b5b3420) by Meagan Lang).
- Added dockerfile and pixi tasks for building/running docker image containing server ([4128bbf](https://github.com/langmm/simulatr/commit/4128bbf9370a8da22075687789d31410e808a60f) by Meagan Lang).
- Added output_vars & timestep fields to model engine for use with server and update how the resume methods works to allow for a variable timestep ([0cb714e](https://github.com/langmm/simulatr/commit/0cb714eba254c59b06e96d70dc499bacee571666) by Meagan Lang).
- Added soil file base class and ISRIC class for getting data from ISRIC SoilGrids (the REST API is not stable atm so this should not be the default soil data source) Begin matching data model to server Move data classes into data module and add a BaseDataFile class for more uniform treatment of conversion between data files and caching ([bbac3d7](https://github.com/langmm/simulatr/commit/bbac3d7817aae11f09a3d6310b9df1f6d7963c8c) by Meagan Lang).
- Added apsimx conda dependencies to recipe ([caa6fa2](https://github.com/langmm/simulatr/commit/caa6fa23c7b50596556b732206b0ff288f3043bf) by Meagan Lang).
- Added summary job to conda build GHA workflow for use in rulesets Set python_min in recipe context to allow building outside conda-forge Lint ([a5509c1](https://github.com/langmm/simulatr/commit/a5509c149440a2dc9fa53c0aaf685ab60a58ff01) by Meagan Lang).
- Added docs on release process and added badges to README.md ([0ce6982](https://github.com/langmm/simulatr/commit/0ce69826c7705a7b532a2bc012f800df822e100c) by Meagan Lang).
- Added CHANGELOG ([79a894d](https://github.com/langmm/simulatr/commit/79a894d9eb5e6726e0b4292afa0de02b58385541) by Meagan Lang).

## [v0.0.1](https://github.com/langmm/simulatr/releases/tag/v0.0.1) - 2026-08-07

<small>[Compare with first commit](https://github.com/langmm/simulatr/compare/324cfff51d20d4a57f146604e5bbe60959c564f5...v0.0.1)</small>

Initial release migrating from [ApsimXGym](https://github.com/langmm/ApsimX/tree/yggdrasil/ApsimXGym).

### Features included

- Support for ApsimX simulator engine including installation from GitHub
- Classes for running simulator engines interactively
- Classes for running simulator engines as [gymnasium](https://gymnasium.farama.org/) RL environments
- Ability to generated LLM prompts for simulator based RL environments for [AgriManager](https://github.com/CHIGUI0/AgriManager)
- CLI for running simulators and managing simulatr configuration
- pixi environments and tasks
- Sphinx based [documentation](https://langmm.github.io/simulatr) with GHA workflow to automatically updated
- Conda recipe with GHA workflow to build recipe
- Tests for all classes with GHA workflow to run tests
