Skip to main content

ALTRIOS

Altrios Logo

homepage Tests wheels Python Documentation GitHub

Model Framework Schematic

The Advanced Locomotive Technology and Rail Infrastructure Optimization System (ALTRIOS) is a unique, fully integrated, open-source software tool to evaluate strategies for deploying advanced locomotive technologies and associated infrastructure for cost-effective decarbonization. ALTRIOS simulates freight-demand driven train scheduling, mainline meet-pass planning, locomotive dynamics, train dynamics, energy conversion efficiencies, and energy storage dynamics of line-haul train operations. Because new locomotives represent a significant long-term capital investment and new technologies must be thoroughly demonstrated before deployment, this tool provides guidance on the risk/reward tradeoffs of different technology rollout strategies. An open, integrated simulation tool is invaluable for identifying future research needs and making decisions on technology development, routes, and train selection. ALTRIOS was developed as part of a collaborative effort by a team comprising The National Renewable Energy Laboratory (NREL), University of Illinois Urbana-Champaign (UIUC), Southwest Research Institute (SwRI), and BNSF Railway.

Installation

All Users

Python Setup

  1. Python installation options:
  2. Setup a python environment. ALTRIOS can work with Python 3.9, or 3.10, but we recommend 3.10 for better performance and user experience. Create a python environment for ALTRIOS with either of two methods:
    • Option 1 -- Python Venv
      1. Navigate to the ALTRIOS folder you just cloned or any folder you'd like for using ALTRIOS. Remember the folder you use!
      2. Assuming you have Python 3.10 installed, run python3.10 -m venv altrios-venv in your terminal enviroment (we recommend PowerShell in Windows, which comes pre-installed). This tells Python 3.10 to use the venv module to create a virtual environment (which will be ignored by git if named altrios-venv) in the ALTRIOS/altrios-venv/.
      3. Activate the environment you just created to install packages or anytime you're running ALTRIOS:
        • Mac and Linux: source altrios-venv/bin/activate
        • Windows: altrios-venv/Scripts/activate.bat in a windows command prompt or power shell or source ./altrios-venv/scripts/activate in git bash terminal
        • When the environment is activated, your terminal session will have a decorator that looks like (altrios-venv).
    • Option 2 -- Anaconda:
      1. Open an Anaconda prompt (in Windows, we recommend Anaconda Powershell Prompt) and run the command conda create -n altrios python=3.10 to create an Anaconda environment named altrios.
      2. Activate the environment to install packages or anytime you're running ALTRIOS: run conda activate altrios.

ALTRIOS Setup

With your Python environment activated, run pip install altrios.

Congratulations, you've completed installation! Whenever you need to use ALTRIOS, be sure to activate your python environment created above.

Developers

Cloning the GitHub Repo

Clone the repository:

  1. Download and install git -- accept all defaults when installing.
  2. Create a parent directory in your preferred location to contain the repo -- e.g. <USER_HOME>/Documents/altrios_project/.
  3. Open git bash, and inside the directory you created, clone the ALTRIOS repository with e.g. git clone https://github.com/NREL/ALTRIOS.git.

Installing the Python Package

Within the ALTRIOS folder, run pip install -e ".[dev]"

Using Pinned Package Versions

If you want to use pinned package versions to make sure you're environment is the same as the developers, you can do:

pip install -r requirements-dev.txt

Updating Pinned Package Versions

If you add a new package as a dependency, you should update the pinned requirements files. To do this you can install pip tools: pip install pip-tools and then:

pip-compile && pip-compile requirements-dev.in

This will generate two files: requirements.txt and requirements-dev.txt which you can check into the repository.

Rust Installation

Install Rust: https://www.rust-lang.org/tools/install.

Automated Building and Testing

There is a shortcut for building and running all tests, assuming you've installed the python package with develop mode. In the root of the ALTRIOS/ folder, run the build_and_test.sh script. In Windows bash (e.g. git bash), run sh build_and_test.sh, or in Linux/Unix, run ./build_and_test.sh. This builds all the Rust code, runs Rust tests, builds the Python-exposed Rust code, and runs the Python tests.

Manually Building the Python API

Run maturin develop --release. Note that not including --release will cause a significant runtime computational performance penalty.

Testing

Manually

Whenever updating code, always run cargo test --release inside ALTRIOS/rust/ to ensure that all tests pass. Also, be sure to rebuild the Python API regularly to ensure that it is up to date. Python unit tests run with python -m unittest discover in the root folder of the git repository.

With GitHub Actions

Any time anyone pushes to main or does any pull request, the GitHub Actions tests workflow is triggered.

Releasing

To PyPI With GitHub Actions

To release the package with GitHub Actions, you can follow these steps:

  1. With the changes already committed, create a new branch in the format v<major>.<minor>.<patch>. For example v0.2.1.
  2. Update the version number in the pyproject.toml file. Commit and push to https://github.com/NREL/altrios.
  3. Open a pull request into the main branch and make sure all checks pass.
  4. Once the pull request is merged into the main branch by a reviewer, create a new GitHub release and create a tag that matches the branch name. Once the release is created, a GitHub action will be launched to build the wheels and publish them to PyPI.

To crates.io

Instructions for releasing altrios-core and altrios-proc-macros are found in the README.md files in both of these crates. altrios-core-py is a cdylib crate and cannot be released.

How to run ALTRIOS

With your activated Python environment with ALTRIOS fully installed, you can download the demo scripts to the current working directory inside of a demos/ folder with:

import altrios as alt  
alt.copy_demo_files()

You can run the Simulation Manager through a multi-week simulation of train operations in by running python sim_manager_demo.py in demos/. This will create a plots/ subfolder in which the plots will be saved. To run interactively, fire up a Python IDE (e.g. VS Code, Spyder), and run the file. If you're in VS Code, you can run the file as a virtual jupyter notebook because of the "cells" that are marked with the # %% annotation. You can click on line 2, for example, and hit <Shift> + <Enter> to run the current cell in an interactive terminal (which will take several seconds to launch) and advance to the next cell. Alternatively, you can hit <Ctrl> + <Shift> + p to enable interactive commands and type "run current cell". There are several other python files in the demos/ folder to demonstrate various capabilities of ALTRIOS.

Acknowledgements

  The ALTRIOS Team would like to thank ARPA-E for financially supporting the research through the LOCOMOTIVES program and Dr. Robert Ledoux for his vision and support. We would also like to thank the ARPA-E team for their support and guidance: Dr. Apoorv Agarwal, Mirjana Marden, Alexis Amos, and Catherine Good. We would also like to thank BNSF for their cost share financial support, guidance, and deep understanding of the rail industry’s needs. Additionally, we would like to thank Jinghu Hu for his contributions to the core ALTRIOS code. We would like to thank Chris Hennessy at SwRI for his support. Thank you to Michael Cleveland for his help with developing and kicking off this project.

Metadata

Release files for altrios 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for altrios 0.1.4
File Size Uploaded Provenance Actions
altrios-0.1.4.tar.gz 1.8 MB Without provenance Details for altrios-0.1.4.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for altrios 0.1.4
File Actions
altrios-0.1.4-cp310-none-win_amd64.whl CPython 3.10 none Windows x86-64 Details for altrios-0.1.4-cp310-none-win_amd64.whl
altrios-0.1.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.17+ x86-64 Details for altrios-0.1.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
altrios-0.1.4-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl CPython 3.10 CPython 3.10 macOS 10.12+ universal2 (ARM64, x86-64), macOS 11.0+ ARM64, macOS 10.12+ x86-64 Details for altrios-0.1.4-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
altrios-0.1.4-cp39-none-win_amd64.whl CPython 3.9 none Windows x86-64 Details for altrios-0.1.4-cp39-none-win_amd64.whl
altrios-0.1.4-cp39-cp39-manylinux_2_35_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.35+ x86-64 Details for altrios-0.1.4-cp39-cp39-manylinux_2_35_x86_64.whl
altrios-0.1.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.17+ x86-64 Details for altrios-0.1.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
altrios-0.1.4-cp39-cp39-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl CPython 3.9 CPython 3.9 macOS 11.0+ ARM64, macOS 10.12+ x86-64, macOS 10.12+ universal2 (ARM64, x86-64) Details for altrios-0.1.4-cp39-cp39-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Total release size: 102.8 MB

Release files / altrios-0.1.4.tar.gz

Download URL altrios-0.1.4.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
1f6a67f5f1e03579d7e71c12268f22203a6337b6709e4687c7e2fdf54e04a29a
BLAKE2b-256 checksum
How to use checksums
bb59d87bdd21f736d2899f48db68fc586a962e64a5edc8fd645b15b57ce9ab89
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Release files / altrios-0.1.4-cp310-none-win_amd64.whl

Download URL altrios-0.1.4-cp310-none-win_amd64.whl
Size 10.7 MB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
5deaf5a7cbffe952519aa0b18fcd3a4a3f450962ebd5d6614600662e2cd0b4b8
BLAKE2b-256 checksum
How to use checksums
30997b7c5f82ac3d09c8c71b192bb78e9fc9bacc220858b1504d95b994655fe9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Release files / altrios-0.1.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL altrios-0.1.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 13.1 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
7b5a6aa9e19de519eca33e9d1c63c88bd4074aef866bf9e39d88f7f7a1c4840a
BLAKE2b-256 checksum
How to use checksums
5cff1aef51b9d861fee979f0288637a390fb831f1f70bd5c0915219cd6309d80
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Release files / altrios-0.1.4-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Download URL altrios-0.1.4-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Size 19.6 MB
Tags CPython 3.10 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
e8a44c6a7f4c7619724ea03a2202bcee57ccbae6adf55fa4567bcddc5ff2c541
BLAKE2b-256 checksum
How to use checksums
7ceee871675d4c5e78d4e26b7cb7e7a73bba398b42c5363d5e3c31021ff46bef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Release files / altrios-0.1.4-cp39-none-win_amd64.whl

Download URL altrios-0.1.4-cp39-none-win_amd64.whl
Size 10.7 MB
Tags CPython 3.9 Windows x86-64
SHA-256 checksum
How to use checksums
98a1e13fcc59948d06e1f36c0e859525b93b02ecec5312b335593378bd3819db
BLAKE2b-256 checksum
How to use checksums
246032531e095f6a1c4f99242f7333d8cf1e51f27aeb1eac1038c2586faf2852
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Release files / altrios-0.1.4-cp39-cp39-manylinux_2_35_x86_64.whl

Download URL altrios-0.1.4-cp39-cp39-manylinux_2_35_x86_64.whl
Size 14.3 MB
Tags CPython 3.9 Linux glibc 2.35+ x86-64
SHA-256 checksum
How to use checksums
60f49f5dce719f468032f13850be670554afe409af6df8207cacf7e2a0a35699
BLAKE2b-256 checksum
How to use checksums
8523d5d5c38f9873b0c7e00e3df28817484b2d8f4b05b79cc948adfdfb47b687
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Release files / altrios-0.1.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL altrios-0.1.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 13.1 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
0c7a7fb492f99e86b2850ae6863b16f65be3e3f5aef1ac98192c3935e6334ac6
BLAKE2b-256 checksum
How to use checksums
159c9bea9c4fc2719b4df43dd40de61e4016b24d8918301282601f41c8e26f41
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Release files / altrios-0.1.4-cp39-cp39-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Download URL altrios-0.1.4-cp39-cp39-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Size 19.6 MB
Tags CPython 3.9 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
9953630d65712ec75a9bfa7526dc93db31640044ea6edd05365f588fd43f0119
BLAKE2b-256 checksum
How to use checksums
b52385f7fd688a08aa2ea2bfdbf999f25271cb35b90e9a2e61df40d16a6ab699
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/4.0.2 CPython/3.11.7

Security for altrios 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page