AMIRIS-Py

Python tools for the electricity market model AMIRIS.

Installation

pip install amirispy

You may also use pipx. For detailed information please refer to the official pipx documentation.

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)

Usage

Currently, there are three distinct commands available:

• amiris download: download the latest versions of AMIRIS and 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.

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.

amiris run

Compile scenario, execute AMIRIS, and extract results.

Bug in argparse

:warning: If you provide but a single flag to --output-options or --core-options, you may get a crash as there is a bug in the argparse library which will not be fixed. We recommend the workaround: Add an equal between the amiris-py option name and its argument, e.g., 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.

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

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.

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:

Example: amiris --log debug --logfile my/log/file.txt download

Cite AMIRIS-Py

If you use AMIRIS-Py in academic work, please cite 10.21105/joss.05041

@article{Schimeczek2023, 
  title = {{AMIRIS}: Agent-based Market model for the Investigation of Renewable and Integrated energy Systems}, 
  author = {Schimeczek, Christoph and Nienhaus, Kristina and Frey, Ulrich and Sperber, Evelyn and Sarfarazi, Seyedfarzad and Nitsch, Felix and Kochems, Johannes and Ghazi, A. Achraf El}, 
  journal = {Journal of Open Source Software}, 
  year = {2023}, 
  volume = {8}, 
  number = {84}, 
  pages = {5041}, 
  publisher = {The Open Journal}, 
  doi = {10.21105/joss.05041}, 
} 

Contributing

Please see CONTRIBUTING.

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 or via amiris@dlr.de. Please report bugs and make feature requests by filing issues following the provided templates (see also CONTRIBUTING). For substantial enhancements, we recommend that you contact us via 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.