Tool for modeling and optimization of advanced locomotive powertrains for freight rail decarbonization.
Project description
ALTRIOS
The Advanced Locomotive Technology and Rail Infrastructure Optimization System (ALTRIOS) is a tool for simulating and optimizing the rollout of advanced locomotive technologies and associated infrastructure with the goal of decarbonizing freight rail. ALTRIOS-lite will be released no later than June 2023, but for a richer, full-featured experience, we recommend using ALTRIOS through the Python API user interface, and we offer full installation instructions and numerous usage examples.
Installation
Python Setup
- Python installation options:
- Option 1 -- Python: https://www.python.org/downloads/. We recommend Python 3.10. Be sure to check the
Add to PATH
option during installation. - Option 2 -- Anaconda: we recommend https://docs.conda.io/en/latest/miniconda.html.
- Option 1 -- Python: https://www.python.org/downloads/. We recommend Python 3.10. Be sure to check the
- Setup a python environment. ALTRIOS can work with Python 3.8, 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
- Navigate to the ALTRIOS folder you just cloned or any folder you'd like for using ALTRIOS. Remember the folder you use!
- 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 thevenv
module to create a virtual environment (which will be ignored by git if namedaltrios-venv
) in theALTRIOS/altrios-venv/
. - 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 orsource ./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)
.
- Mac and Linux:
- Option 2 -- Anaconda:
- 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 namedaltrios
. - Activate the environment to install packages or anytime you're running ALTRIOS: run
conda activate altrios
.
- Open an Anaconda prompt (in Windows, we recommend Anaconda Powershell Prompt) and run the command
- Option 1 -- Python Venv
ALTRIOS Setup
ALTRIOS can be install from PyPI. 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.
How to run ALTRIOS
With your activated Python environment with ALTRIOS fully installed, you can run several scripts in ALTRIOS/applications/demos/
.
You can run the Simulation Manager through a multi-week simulation of train operations with ALTRIOS/applications/demos/sim_manager_demo.py
by running python sim_manager_demo.py
in ALTRIOS/applications/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".
Developers
Cloning the GitHub Repo
Clone the repository:
- Download and install git -- accept all defaults when installing.
- Create a parent directory in your preferred location to contain the repo -- e.g.
<USER_HOME>/Documents/altrios_project/
. - 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 computational performance penalty.
Manually Testing
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.
Releasing
To release the package, you can following these steps:
- Create a new branch in the format
v<major>.<minor>.<patch>
. For examplev0.2.1
. - Update the version number in the
pyproject.toml
file. - Open a pull request into the main branch and make sure all checks pass.
- Once the pull request is merged into the main branch, 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for altrios-0.1.0.post2-cp310-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3c6cb9d15a4e373e3994564c0e71c3c6ed77ff6fe83e010a104dd2da0792f840 |
|
MD5 | cc6601226b8a50d66f3721b5445bdc10 |
|
BLAKE2b-256 | c180ab0314ce8d613654d397d3224e02568640fc5c6e45447bde92cb36ed9fff |
Hashes for altrios-0.1.0.post2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 678b29fafa77a2d8e344105a3ebdb6d3574b2e4d965898fa170ab1c6d9b166fb |
|
MD5 | cf7359d48eed98a6ed197aa8f2f0857f |
|
BLAKE2b-256 | 6709598912cf7643a023a3c56bd2fd193caa9259d0978dce8e1651067bd9858e |
Hashes for altrios-0.1.0.post2-cp310-cp310-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 12d1c8854062cad1551004294e92ae505fcd404f462203c8517138d7ee5f1c1a |
|
MD5 | 195ca4cc2ddd3dc5bece8377ecfa80b9 |
|
BLAKE2b-256 | 8ee4587af63580b1411a89430f4999ce697720d7ae5efaaffae61833ed63b7e4 |
Hashes for altrios-0.1.0.post2-cp39-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e26994a9b525fe28d9d44f2d3b9a0770afa688bb82f94d945d641271eb614037 |
|
MD5 | 36852887d4788317574222a1187c7125 |
|
BLAKE2b-256 | 3468f83c0bac960e5f93df7d4bbc953232dd2827656b638b9fccdd546598dbf4 |
Hashes for altrios-0.1.0.post2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 75f412ab0110c243ad6eef4fc0b2effa5c7ede6275a4c7a740eca31297f52f02 |
|
MD5 | 06363a48a8e154493f5863f8155feb74 |
|
BLAKE2b-256 | f81c8d60d5f34a0ad83c59182e94a95d825e5fde1f57b07806d3d64ccfba525b |
Hashes for altrios-0.1.0.post2-cp39-cp39-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3414fe88eb09d2a8b1cc78f1a9dcc475318627d6549487ac31a78ade0eca2ec4 |
|
MD5 | c6b6e7901067a7624946f353b9d4e850 |
|
BLAKE2b-256 | 1ef6a7c53b9f5da4f81e3657e997fb54df76a74f41a5060075fe405c131e60e6 |
Hashes for altrios-0.1.0.post2-cp38-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b67e978497e399943830bf13b9e5150e3838dcb76392450050574d60db2df5ab |
|
MD5 | 50be107520762da0a956485663201dfb |
|
BLAKE2b-256 | 5f8a5f268a6617d5bdfef7b1d37ce9b9649b2fc6e4942e5c08900e4b9ae4cef8 |
Hashes for altrios-0.1.0.post2-cp38-cp38-manylinux_2_34_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 27828bc40c8a61a9bb270a2013ab780c051104d57e877efe42197a47f68762ae |
|
MD5 | e0f872d24f2046be5df8de04bae09fc4 |
|
BLAKE2b-256 | 3befa588a6f5ae5324fdbbe31c42b1dbb4ffecf020fda136cb3ae15773a63954 |
Hashes for altrios-0.1.0.post2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f592ef11f1140d5208934785d672dfb72a74c717c290581d7d174b3fa1c6f510 |
|
MD5 | ceb83914f02dd26f8b16ec58911ecb2b |
|
BLAKE2b-256 | 8d268014dfe57925f409c0de5e56f6bd42484e3ab45291b0467a6d83a8f66482 |
Hashes for altrios-0.1.0.post2-cp38-cp38-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2f018d1323f673fcf6f11941fe644099a73b1edba27b85580cdc40da570a13b6 |
|
MD5 | bef4341f517c41814fdd92e003dd2b98 |
|
BLAKE2b-256 | 959c1c57d3a6e12fd1e315d41adc5397bc0a0e08bb12cd51585ab0f01ce86d66 |