<!-- SPDX-FileCopyrightText: 2025 German Aerospace Center <amiris@dlr.de>
SPDX-License-Identifier: Apache-2.0 -->
[](https://badge.fury.io/py/amirispy)
[](https://badge.fury.io/py/amirispy)
[](https://gitlab.com/dlr-ve/esy/amiris/amiris-py/commits/main)
# AMIRIS-Py
Python tools for the electricity market model [AMIRIS](https://dlr-ve.gitlab.io/esy/amiris/home/).
## Installation
pip install amirispy
You may also use `pipx`. For detailed information please refer to the
official `pipx` [documentation](https://github.com/pypa/pipx).
pipx install amirispy
### Further Requirements
In order to execute all commands provided by `amirispy`, you also require a Java Development Kit (JDK).
JDK must be installed and accessible via your console in which you run `amirispy`.
To test, run `java --version` which should show your JDK version (required: 11 or above).
If `java` command is not found or relates to a Java Runtime Environment (JRE), please download and install JDK (e.g. from [Adoptium](https://adoptium.net/de/temurin/releases/?version=17))
## Usage
Currently, there are three distinct commands available:
- `amiris download`: download the latest versions of [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) and [examples](https://gitlab.com/dlr-ve/esy/amiris/examples) files
- `amiris run`: perform a full workflow by compiling the `.pb` file from your `scenario.yaml`, executing AMIRIS, and extracting the results
- `amiris batch`: perform multiple runs, each with scenario compilation, AMIRIS execution, and results extraction
- `amiris comparison`: compare the results of two different AMIRIS runs to check their equivalence
You may also use the arguments as a list of strings in your script directly, e.g.
```python
from amirispy.scripts import amiris_cli
amiris_cli(["download", "-m", "model"])
```
### `amiris download`
Downloads and extracts the latest open access AMIRIS instance and accompanying examples.
| Option | Provides |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-u` or `--url` | URL to download AMIRIS from (default: latest AMIRIS artifact from [https://gitlab.com/dlr-ve/esy/amiris/amiris](https://gitlab.com/dlr-ve/esy/amiris/amiris) |
| `-t` or `--target` | Folder to download `amiris-core_<version>-jar-with-dependencies.jar` to (default: `./`) |
| `-f` or `--force` | Force download which may overwrites existing AMIRIS installation of same version and existing examples (default: False) |
| `-m` or `--mode` | Option to download model and examples `all` (default), only `model`, or only `examples` |
### `amiris run`
Compile scenario, execute AMIRIS, and extract results.
| Option | Provides |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-s` or `--scenario` | Path to a scenario yaml-file |
| `-j` or `--jar` | Path to `amiris-core_<version>-jar-with-dependencies.jar`, defaults to a single "amiris*.jar"-file in current working directory |
| `-o` or `--output` | Directory to write output to, defaults to "./result" |
| `-oo` or `--output-options` | Optional arguments to override default output [conversion arguments of fameio](https://gitlab.com/fame-framework/fame-io/-/blob/main/README.md#read-fame-results) |
| `-nc` or `--no-checks` | Skip checks for Java installation and correct version to increase speed |
#### Bug in argparse
:warning: If you provide but a single flag to `--output-option`, you may get a crash as there is a [bug](https://bugs.python.org/issue9334) in the `argparse` library which will not be fixed.
We recommend these workarounds:
* provide additional parameters, e.g. for the log level: change `-oo "-m"` to `-oo "-m -l critical"`, or
* add a space after the single flag: change `-oo "-m"` to `-oo "-m "`
#### Calling AMIRIS from your own script using `amiris_cli`
If you happen to run AMIRIS in your own script by importing `amiris_cli`, this is an example of how to use it.
```python
from amirispy.scripts import amiris_cli
commands = [
"-l", "critical",
"run",
"-j", "amiris-core_3.4.0-jar-with-dependencies.jar",
"-s", "examples/Germany2019/scenario.yaml",
"-oo", "-m ",
]
amiris_cli(commands)
```
:warning: Similar to the command-line call you need to work around the argparse bug when using `--output-option` with a single flag only.
Thus, the extra space in statement `"-oo", "-m "` is intended - see explanation above.
### `amiris batch`
Perform multiple runs - each with scenario compilation, AMIRIS execution, and results extraction
| Option | Provides |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-s` or `--scenarios` | Path to single or list of: scenario yaml-files or their enclosing directories |
| `-j` or `--jar` | Path to `amiris-core_<version>-jar-with-dependencies.jar`, defaults to a single "amiris*.jar"-file in current working directory |
| `-o` or `--output` | Directory to write output to "./result" |
| `-r` or `--recursive` | Option to recursively search in provided Path for scenario (default: False) |
| `-p` or `--pattern` | Optional name pattern that scenario files searched for must match |
| `-oo` or `--output-options` | Optional arguments to override default output [conversion arguments of fameio](https://gitlab.com/fame-framework/fame-io/-/blob/main/README.md#read-fame-results) |
| `-nc` or `--no-checks` | Skip checks for Java installation and correct version to increase speed |
See description of `amiris run` for details on the issues with the `-oo` option.
### `amiris compare`
Compare if results of two AMIRIS runs and equivalent.
| Option | Provides |
|----------------------|--------------------------------------------------------------------|
| `-e` or `--expected` | Path to folder with expected result .csv files |
| `-t` or `--test` | Path to folder with results files (.csv) to test for equivalence |
| `-i` or `--ignore` | Optional list of file names not to be compared |
### Help
You reach the help menu at any point using `-h` or `--help` which gives you a list of all available options, e.g.:
`amiris --help`
### Logging
You may define a logging level or optional log file as **first** arguments in your workflow using any of the following
arguments:
| Option | Provides |
|----------------------|----------------------------------------------------------------------------------------------------------|
| `-l` or `--log` | logging level, defaults to `error`; options are `debug`, `info`, `warning`, `warn`, `error`, `critical`. |
| `-lf` or `--logfile` | path to log file, defaults to `None`; if `None` is provided, all logs get only printed to the console. |
Example: `amiris --log debug --logfile my/log/file.txt download`
## Cite AMIRIS-Py
If you use AMIRIS-Py for academic work, please cite:
Christoph Schimeczek, Kristina Nienhaus, Ulrich Frey, Evelyn Sperber, Seyedfarzad Sarfarazi, Felix Nitsch, Johannes Kochems & A. Achraf El Ghazi (2023).
AMIRIS: Agent-based Market model for the Investigation of Renewable and Integrated energy Systems.
Journal of Open Source Software. doi: [10.21105/joss.05041](https://doi.org/10.21105/joss.05041)
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md).
## Available Support
This is a purely scientific project by (at the moment) one research group.
Thus, there is no paid technical support available.
If you experience any trouble with AMIRIS, you may contact the developers at the [openMod-Forum](https://forum.openmod.org/tag/amiris) or via [amiris@dlr.de](mailto:amiris@dlr.de).
Please report bugs and make feature requests by filing issues following the provided templates (see also [CONTRIBUTING](CONTRIBUTING.md)).
For substantial enhancements, we recommend that you contact us via [amiris@dlr.de](mailto:amiris@dlr.de) for working together on the code in common projects or towards common publications and thus further develop AMIRIS.
## Acknowledgement
Work on AMIRIS-Py was financed by the Helmholtz Association's Energy System Design research programme.
Raw data
{
"_id": null,
"home_page": "https://helmholtz.software/software/amiris",
"name": "amirispy",
"maintainer": "Christoph Schimeczek",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": "amiris@dlr.de",
"keywords": "AMIRIS, agent-based modelling, electricity market",
"author": "Christoph Schimeczek",
"author_email": "amiris@dlr.de",
"download_url": "https://files.pythonhosted.org/packages/ed/76/fded0b4002a02ecb944143d797dd21b2bbb998570583fca3c89157c12d53/amirispy-3.3.1.tar.gz",
"platform": null,
"description": "<!-- SPDX-FileCopyrightText: 2025 German Aerospace Center <amiris@dlr.de>\n\nSPDX-License-Identifier: Apache-2.0 -->\n\n[](https://badge.fury.io/py/amirispy)\n[](https://badge.fury.io/py/amirispy)\n[](https://gitlab.com/dlr-ve/esy/amiris/amiris-py/commits/main)\n\n# AMIRIS-Py\n\nPython tools for the electricity market model [AMIRIS](https://dlr-ve.gitlab.io/esy/amiris/home/).\n\n## Installation\n\n pip install amirispy\n\nYou may also use `pipx`. For detailed information please refer to the\nofficial `pipx` [documentation](https://github.com/pypa/pipx).\n\n pipx install amirispy\n\n### Further Requirements\n\nIn order to execute all commands provided by `amirispy`, you also require a Java Development Kit (JDK).\nJDK must be installed and accessible via your console in which you run `amirispy`.\n\nTo test, run `java --version` which should show your JDK version (required: 11 or above).\nIf `java` command is not found or relates to a Java Runtime Environment (JRE), please download and install JDK (e.g. from [Adoptium](https://adoptium.net/de/temurin/releases/?version=17))\n\n## Usage\n\nCurrently, there are three distinct commands available:\n\n- `amiris download`: download the latest versions of [AMIRIS](https://gitlab.com/dlr-ve/esy/amiris/amiris) and [examples](https://gitlab.com/dlr-ve/esy/amiris/examples) files\n- `amiris run`: perform a full workflow by compiling the `.pb` file from your `scenario.yaml`, executing AMIRIS, and extracting the results\n- `amiris batch`: perform multiple runs, each with scenario compilation, AMIRIS execution, and results extraction\n- `amiris comparison`: compare the results of two different AMIRIS runs to check their equivalence\n\nYou may also use the arguments as a list of strings in your script directly, e.g.\n\n```python\nfrom amirispy.scripts import amiris_cli\n\namiris_cli([\"download\", \"-m\", \"model\"])\n```\n\n### `amiris download`\n\nDownloads and extracts the latest open access AMIRIS instance and accompanying examples.\n\n| Option | Provides |\n|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `-u` or `--url` | URL to download AMIRIS from (default: latest AMIRIS artifact from [https://gitlab.com/dlr-ve/esy/amiris/amiris](https://gitlab.com/dlr-ve/esy/amiris/amiris) |\n| `-t` or `--target` | Folder to download `amiris-core_<version>-jar-with-dependencies.jar` to (default: `./`) |\n| `-f` or `--force` | Force download which may overwrites existing AMIRIS installation of same version and existing examples (default: False) |\n| `-m` or `--mode` | Option to download model and examples `all` (default), only `model`, or only `examples` |\n\n### `amiris run`\n\nCompile scenario, execute AMIRIS, and extract results.\n\n| Option | Provides |\n|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `-s` or `--scenario` | Path to a scenario yaml-file |\n| `-j` or `--jar` | Path to `amiris-core_<version>-jar-with-dependencies.jar`, defaults to a single \"amiris*.jar\"-file in current working directory |\n| `-o` or `--output` | Directory to write output to, defaults to \"./result\" |\n| `-oo` or `--output-options` | Optional arguments to override default output [conversion arguments of fameio](https://gitlab.com/fame-framework/fame-io/-/blob/main/README.md#read-fame-results) |\n| `-nc` or `--no-checks` | Skip checks for Java installation and correct version to increase speed |\n\n#### Bug in argparse\n\n:warning: If you provide but a single flag to `--output-option`, you may get a crash as there is a [bug](https://bugs.python.org/issue9334) in the `argparse` library which will not be fixed.\nWe recommend these workarounds:\n\n* provide additional parameters, e.g. for the log level: change `-oo \"-m\"` to `-oo \"-m -l critical\"`, or\n* add a space after the single flag: change `-oo \"-m\"` to `-oo \"-m \"`\n\n#### Calling AMIRIS from your own script using `amiris_cli`\n\nIf you happen to run AMIRIS in your own script by importing `amiris_cli`, this is an example of how to use it.\n\n```python\nfrom amirispy.scripts import amiris_cli\n\ncommands = [\n \"-l\", \"critical\",\n \"run\",\n \"-j\", \"amiris-core_3.4.0-jar-with-dependencies.jar\",\n \"-s\", \"examples/Germany2019/scenario.yaml\",\n \"-oo\", \"-m \",\n]\n\namiris_cli(commands)\n```\n\n:warning: Similar to the command-line call you need to work around the argparse bug when using `--output-option` with a single flag only.\nThus, the extra space in statement `\"-oo\", \"-m \"` is intended - see explanation above.\n\n### `amiris batch`\n\nPerform multiple runs - each with scenario compilation, AMIRIS execution, and results extraction\n\n| Option | Provides |\n|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `-s` or `--scenarios` | Path to single or list of: scenario yaml-files or their enclosing directories |\n| `-j` or `--jar` | Path to `amiris-core_<version>-jar-with-dependencies.jar`, defaults to a single \"amiris*.jar\"-file in current working directory |\n| `-o` or `--output` | Directory to write output to \"./result\" |\n| `-r` or `--recursive` | Option to recursively search in provided Path for scenario (default: False) |\n| `-p` or `--pattern` | Optional name pattern that scenario files searched for must match |\n| `-oo` or `--output-options` | Optional arguments to override default output [conversion arguments of fameio](https://gitlab.com/fame-framework/fame-io/-/blob/main/README.md#read-fame-results) |\n| `-nc` or `--no-checks` | Skip checks for Java installation and correct version to increase speed |\n\nSee description of `amiris run` for details on the issues with the `-oo` option.\n\n### `amiris compare`\n\nCompare if results of two AMIRIS runs and equivalent.\n\n| Option | Provides |\n|----------------------|--------------------------------------------------------------------|\n| `-e` or `--expected` | Path to folder with expected result .csv files |\n| `-t` or `--test` | Path to folder with results files (.csv) to test for equivalence |\n| `-i` or `--ignore` | Optional list of file names not to be compared |\n\n### Help\n\nYou reach the help menu at any point using `-h` or `--help` which gives you a list of all available options, e.g.:\n\n`amiris --help`\n\n### Logging\n\nYou may define a logging level or optional log file as **first** arguments in your workflow using any of the following\narguments:\n\n| Option | Provides |\n|----------------------|----------------------------------------------------------------------------------------------------------|\n| `-l` or `--log` | logging level, defaults to `error`; options are `debug`, `info`, `warning`, `warn`, `error`, `critical`. |\n| `-lf` or `--logfile` | path to log file, defaults to `None`; if `None` is provided, all logs get only printed to the console. |\n\nExample: `amiris --log debug --logfile my/log/file.txt download`\n\n## Cite AMIRIS-Py\n\nIf you use AMIRIS-Py for academic work, please cite:\n\nChristoph Schimeczek, Kristina Nienhaus, Ulrich Frey, Evelyn Sperber, Seyedfarzad Sarfarazi, Felix Nitsch, Johannes Kochems & A. Achraf El Ghazi (2023).\nAMIRIS: Agent-based Market model for the Investigation of Renewable and Integrated energy Systems.\nJournal of Open Source Software. doi: [10.21105/joss.05041](https://doi.org/10.21105/joss.05041)\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md).\n\n## Available Support\n\nThis is a purely scientific project by (at the moment) one research group.\nThus, there is no paid technical support available.\n\nIf you experience any trouble with AMIRIS, you may contact the developers at the [openMod-Forum](https://forum.openmod.org/tag/amiris) or via [amiris@dlr.de](mailto:amiris@dlr.de).\nPlease report bugs and make feature requests by filing issues following the provided templates (see also [CONTRIBUTING](CONTRIBUTING.md)).\nFor substantial enhancements, we recommend that you contact us via [amiris@dlr.de](mailto:amiris@dlr.de) for working together on the code in common projects or towards common publications and thus further develop AMIRIS.\n\n## Acknowledgement\n\nWork on AMIRIS-Py was financed by the Helmholtz Association's Energy System Design research programme.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python tools for the open electricity market model AMIRIS",
"version": "3.3.1",
"project_urls": {
"Changelog": "https://gitlab.com/dlr-ve/esy/amiris/amiris-py/-/blob/main/CHANGELOG.md",
"Homepage": "https://helmholtz.software/software/amiris",
"Issue Tracking": "https://gitlab.com/dlr-ve/esy/amiris/amiris-py/-/issues",
"Repository": "https://gitlab.com/dlr-ve/esy/amiris/amiris-py"
},
"split_keywords": [
"amiris",
" agent-based modelling",
" electricity market"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d50d36b6168840cd8f2b76e1e3ad1e02020c23e0e62ba286f7da76e763cb0905",
"md5": "7b8ec54a44156da4b2e3490074a54f5d",
"sha256": "a9bf860c044b1b1119f4f645c979476e9efa96f610e8b223b751b133dd7b80b9"
},
"downloads": -1,
"filename": "amirispy-3.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b8ec54a44156da4b2e3490074a54f5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 35868,
"upload_time": "2025-08-11T14:26:17",
"upload_time_iso_8601": "2025-08-11T14:26:17.204015Z",
"url": "https://files.pythonhosted.org/packages/d5/0d/36b6168840cd8f2b76e1e3ad1e02020c23e0e62ba286f7da76e763cb0905/amirispy-3.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed76fded0b4002a02ecb944143d797dd21b2bbb998570583fca3c89157c12d53",
"md5": "82a37cc9ae60759c0a87a904fa71c135",
"sha256": "dc49e9e572e2281e7e9adac21c66c83883ac1a1dc035600710313cbb3ea9af44"
},
"downloads": -1,
"filename": "amirispy-3.3.1.tar.gz",
"has_sig": false,
"md5_digest": "82a37cc9ae60759c0a87a904fa71c135",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 30972,
"upload_time": "2025-08-11T14:26:18",
"upload_time_iso_8601": "2025-08-11T14:26:18.715782Z",
"url": "https://files.pythonhosted.org/packages/ed/76/fded0b4002a02ecb944143d797dd21b2bbb998570583fca3c89157c12d53/amirispy-3.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 14:26:18",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "dlr-ve",
"gitlab_project": "esy",
"lcname": "amirispy"
}
JSON