Merge branch 'main' of github.com:NREL/altrios into windows_intructions

# Conflicts:
#	README.md

.github/workflows/deploy-book.yaml

@@ -8,6 +8,7 @@ on:
       - "docs/**"
       - ".github/workflows/deploy-book.yaml"
       - "README.md"
+      - "python/**"
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -33,11 +34,25 @@ jobs:
       MDBOOK_VERSION: 0.4.21
     steps:
       - uses: actions/checkout@v3
-      - name: Install mdBook
+      - name: Install mdBook and supporting dependencies
         run: |
           curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
           rustup update
-          cargo install --version ${MDBOOK_VERSION} mdbook
+          cargo install --version ${MDBOOK_VERSION} mdbook 
+          cargo install mdbook-toc 
+
+      - name: Install dependencies for python docs
+        run: 
+          sudo apt update &&
+          sudo apt install pipx &&
+          pipx ensurepath &&
+          pipx install pydoc-markdown
+
+      - name: Generate python docs
+        working-directory: ${{runner.workspace}}/altrios/
+        run:
+          pydoc-markdown -I python/ --render-toc > docs/src/api-doc/python-doc.md
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v3

.github/workflows/tests.yaml → .github/workflows/py-tests.yaml

@@ -1,15 +1,24 @@
-name: tests 
+name: py-tests 
 
 on:
   push:
-      branches: [ main ]
+    branches: [ main ]
+    paths:
+      - "python/**"
+      - "rust/**"
   pull_request:
+    paths:
+      - "python/**"
+      - "rust/**"
   workflow_dispatch:
   workflow_call:
 
 
 jobs:
+  call-rust-tests:
+    uses: nrel/altrios/.github/workflows/rust-tests.yaml@main
   test:
+    needs: call-rust-tests
     if: github.repository == 'nrel/altrios' || github.repository == 'nrel/altrios-private'
 
     runs-on: ubuntu-latest
@@ -31,20 +40,6 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: install rust
-      uses: actions-rs/toolchain@v1
-      with:
-        profile: minimal
-        toolchain: stable 
-        override: true
-
-    - name: Rust unit tests
-      run: |
-        cd rust/
-        cargo test --workspace
-        cd altrios-core/
-        cargo test
-
     - name: Python unit tests 
       run: |
         pip install maturin pytest

.github/workflows/rust-tests.yaml

@@ -0,0 +1,41 @@
+name: rust-tests 
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - "rust/**"
+      - "!python/**"
+  pull_request:
+    paths:
+      - "rust/**"
+      - "!python/**"
+  workflow_dispatch:
+  workflow_call:
+
+
+jobs:
+  test:
+    if: github.repository == 'nrel/altrios' || github.repository == 'nrel/altrios-private'
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: install rust
+      uses: actions-rs/toolchain@v1
+      with:
+        profile: minimal
+        toolchain: stable 
+        override: true
+
+    - name: Rust unit tests
+      run: |
+        cd rust/
+        cargo test --workspace
+        cd altrios-core/
+        cargo test

.github/workflows/wheels.yaml

@@ -9,7 +9,7 @@ on:
 # run tests, build, upload
 jobs:
   call-tests:
-    uses: nrel/altrios/.github/workflows/tests.yaml@main
+    uses: nrel/altrios/.github/workflows/py-tests.yaml@main
   build:
     name: build py3.${{ matrix.python-version }} on ${{ matrix.platform || matrix.os }}
     needs: call-tests
@@ -42,7 +42,7 @@ jobs:
         uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: nightly 
+          toolchain: stable 
           override: true
       - run: rustup target add aarch64-apple-darwin
         if: matrix.os == 'macos'
@@ -70,12 +70,14 @@ jobs:
           CIBW_TEST_SKIP: '*_universal2:arm64'
           CIBW_BEFORE_BUILD: >
             pip install -U maturin &&
-            rustup default nightly &&
+            rustup default stable &&
             rustup show
           CIBW_BEFORE_BUILD_LINUX: >
             pip install -U setuptools-rust &&
-            curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain=nightly --profile=minimal -y &&
+            curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain=stable --profile=minimal -y &&
             rustup show
+          CIBW_BEFORE_BUILD_MACOS: >
+            rustup target add x86_64-apple-darwin
 
       - name: upload artifacts 
         uses: actions/upload-artifact@v3

.gitignore

@@ -1216,3 +1216,4 @@ dkms.conf
 code\ meetings
 altrios/resources/networks/Scenic - ALTRIOS Confidential.yaml
 altrios/dispatch/*.json
+activate.sh

.vscode/launch.json

@@ -41,13 +41,5 @@
             "console": "integratedTerminal",
             "justMyCode": true
         },
-        {
-            "type": "lldb",
-            "request": "launch",
-            "name": "Debug",
-            "program": "${workspaceFolder}/<executable file>",
-            "args": [],
-            "cwd": "${workspaceFolder}"
-        }
     ]
 }

README.md

@@ -2,18 +2,20 @@
 
 ![Altrios Logo](https://raw.githubusercontent.com/NREL/altrios/main/.github/images/ALTRIOS-logo-web.jpg)
 
-[![homepage](https://img.shields.io/badge/homepage-altrios-blue)](https://www.nrel.gov/transportation/altrios.html) [![Tests](https://github.com/NREL/altrios/actions/workflows/tests.yaml/badge.svg)](https://github.com/NREL/altrios/actions/workflows/tests.yaml) [![wheels](https://github.com/NREL/altrios/actions/workflows/wheels.yaml/badge.svg)](https://github.com/NREL/altrios/actions/workflows/wheels.yaml?event=release) [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10-blue)](https://pypi.org/project/altrios/) [![Documentation](https://img.shields.io/badge/documentation-mdBook-blue.svg)](https://nrel.github.io/altrios/) [![GitHub](https://img.shields.io/badge/GitHub-altrios-blue.svg)](https://github.com/NREL/altrios)
+[![homepage](https://img.shields.io/badge/homepage-altrios-blue)](https://www.nrel.gov/transportation/altrios.html) [![rust-tests](https://github.com/NREL/altrios/actions/workflows/rust-tests.yaml/badge.svg)](https://github.com/NREL/altrios/actions/workflows/rust-tests.yaml) [![py-tests](https://github.com/NREL/altrios/actions/workflows/py-tests.yaml/badge.svg)](https://github.com/NREL/altrios/actions/workflows/py-tests.yaml) [![wheels](https://github.com/NREL/altrios/actions/workflows/wheels.yaml/badge.svg)](https://github.com/NREL/altrios/actions/workflows/wheels.yaml?event=release) [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10-blue)](https://pypi.org/project/altrios/) [![Documentation](https://img.shields.io/badge/doc-mdBook-blue.svg)](https://nrel.github.io/altrios/) [![GitHub](https://img.shields.io/badge/GitHub-altrios-blue.svg)](https://github.com/NREL/altrios)
 
 
 ![Model Framework Schematic](https://raw.githubusercontent.com/NREL/altrios/main/.github/images/ALTRIOS_schematic_Alfred_Hicks.png)
 
 The Advanced Locomotive Technology and Rail Infrastructure Optimization System ([ALTRIOS](https://www.nrel.gov/transportation/altrios.html)) 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 Texas (UT), Southwest Research Institute (SwRI), and BNSF Railway.
 
+Much of the core code in ALTRIOS is written in the [Rust Programming Language](https://www.rust-lang.org/) to ensure excellent computational performance and robustness, but we've built ALTRIOS with the intent of users interacting with the code through our feature-rich [Python](https://www.python.org/) interface.  
+
 ## Installation
 
-### All Users
+If you are an ALTRIOS developer, see [Developer Documentation](https://nrel.github.io/altrios/developers.html).  Otherwise, read on.  
 
-#### Python Setup
+### Python Setup
 
 1. 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.
@@ -35,90 +37,38 @@ The Advanced Locomotive Technology and Rail Infrastructure Optimization System (
      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`.
      1. Activate the environment to install packages or anytime you're running ALTRIOS: run `conda activate altrios`.
 
-#### ALTRIOS Setup
+### ALTRIOS Setup
 
 With your Python environment activated, run `pip install altrios`.
-If you choose to opt in developer version, run `python -m pip install “.[dev]”`
 
 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](https://git-scm.com/downloads) -- accept all defaults when installing.
-1. Create a parent directory in your preferred location to contain the repo -- e.g. `<USER_HOME>/Documents/altrios_project/`.
-1. Open git bash, and inside the directory you created, [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) the [ALTRIOS repository](https://github.com/NREL/ALTRIOS) 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:
-
-```shell
-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:
-
-```shell
-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](https://github.com/NREL/altrios/blob/686e8c28828cb980cc45567d08091e69b7bee52c/.github/workflows/tests.yaml#L3) 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`.
-1. Update the version number in the `pyproject.toml` file.  Commit and push to https://github.com/NREL/altrios.  
-1. Open a pull request into the main branch and make sure all checks pass.
-1. 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](https://github.com/NREL/altrios/blob/686e8c28828cb980cc45567d08091e69b7bee52c/.github/workflows/wheels.yaml#L5) 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 [altrios-core README.md](./rust/altrios-core/README.md) and [altrios-proc-macros README.md](./rust/altrios-core/altrios-proc-macros/README.md).  `altrios-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:
 ```python
 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](https://code.visualstudio.com/Download), [Spyder](https://www.spyder-ide.org/)), 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.  
 
+If you plan to modify the data used in the demo files, copy the data files to your local directory and load them  from there, e.g.  
+```python
+res = alt.ReversibleEnergyStorage.from_file(
+   alt.resources_root() / "powertrains/reversible_energy_storages/Kokam_NMC_75Ah_flx_drive.yaml"
+)
+```
+would become  
+```python
+res = alt.ReversibleEnergyStorage.from_file(
+   "./custom_battery.yaml"
+)
+```
+
+Nearly every code object in ALTRIOS can be read from or written to common data formats.  For more details, see [the SerdeAPI trait](https://docs.rs/altrios-core/latest/altrios_core/traits/trait.SerdeAPI.html) documentation.  All of the functions in the SerdeAPI are available through the python interface.  
+
+
+
 ## 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.  

applications/calibration/zanzeff_set_speed_train_cal.py

@@ -116,8 +116,8 @@ def get_train_sim_inputs(df: pd.DataFrame, file_path: Path) -> bytes:
     else:
         raise ValueError("Directionality is invalid.")
 
-    network = alt.import_network(
-        str(alt.package_root() / "../../../data/StockToBar_10thPoint_corrected.yaml"))
+    network = alt.Network.from_file(
+        alt.package_root() / "../../../data/StockToBar_10thPoint_corrected.yaml")
 
     max_offset = network[link_path[0].idx].length_meters - 1e3
 

applications/calibration/zanzeff_set_speed_train_cal_post.py

@@ -3,7 +3,7 @@
 import numpy as np
 import matplotlib.pyplot as plt
 import seaborn as sns
-sns.set()
+sns.set_theme()
 
 from zanzeff_set_speed_train_cal import *
 

build_and_test.sh

@@ -1,10 +1,8 @@
 # assumes a python environment has been created and activated
 echo "Testing rust" && \
 (cd rust/ && cargo test --workspace) && \
-# pip install -qe ".[dev]" && \ 
-# assumes `pip install -qe ".[dev]"` has been run already
 echo "Building python API" && \
-maturin develop --release && \
+pip install -qe ".[dev]" && \ 
 echo "Running python tests" && \
 pytest -v python/altrios/tests && \
 echo "Verifying that demos run" && \

docs/book.toml

@@ -7,4 +7,8 @@ title = "ALTRIOS Documentation"
 
 [output.html.fold]
 enable = true
-level = 0
+level = 0
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]

docs/src/SUMMARY.md

@@ -1,8 +1,10 @@
 # Summary
 
 - [Introduction](./intro.md)
-- [Documentation](./doc.md)
-    - [Rust API](./doc/rust.md)
-        - [Rail Network](./doc/rail-network.md)
+- [Documentation](./api-doc.md)
+    - [Rust API](./api-doc/rust.md)
+        - [Rail Network](./api-doc/rail-network.md)
+    - [Python API](./api-doc/python-doc.md)
+- [Developers](./developers.md)
 - [Press Releases](./press-releases.md)
 - [How to Update This Book](./how-to-update.md)

docs/src/api-doc.md

@@ -0,0 +1,5 @@
+# Documentation
+
+## [Python](./api-doc/python-doc.md)
+
+## [Rust](./doc/rust.md)

docs/src/api-doc/python-doc.md

@@ -0,0 +1 @@
+# Python API Documentation