F3/docs/demos

.github/workflows/deploy_docs.yaml

@@ -45,9 +45,6 @@ jobs:
       - name: Register Jupyter kernel
         run: python -m ipykernel install --user --name python3
 
-      - name: Convert demos to notebooks
-        run: python docs/demos_to_notebooks.py
-
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
@@ -58,10 +55,7 @@ jobs:
         # base path to build correct links to its static assets.
         env:
           BASE_URL: "/${{ github.event.repository.name }}"
-        # TODO: consider adding --strict once a strict + execute build is
-        # confirmed clean, so broken links/refs and execution errors fail the
-        # deploy instead of silently publishing.
-        run: jupyter book build --html --execute
+        run: jupyter book build --strict --html --execute
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

.gitignore

@@ -25,7 +25,6 @@ activate.sh
 .pixi
 *.egg-info
 *.code-workspace
-*.png
 .github/copilot-instructions.md
 
 _build

README.md

@@ -1,90 +1,49 @@
-<img src="https://raw.githubusercontent.com/NatLabRockies/fastsim/refs/heads/fastsim-2/docs/assets/fastsim-icon.svg" height="200">
+<img src="docs/assets/fastsim-icon.svg" height="250">
 
-[![homepage](https://img.shields.io/badge/homepage-fastsim-blue)](https://www.nlr.gov/transportation/fastsim.html)
-[![tests](https://github.com/NatLabRockies/fastsim/actions/workflows/tests.yaml/badge.svg)](https://github.com/NatLabRockies/fastsim/actions/workflows/tests.yaml)
-[![release](https://github.com/NatLabRockies/fastsim/actions/workflows/release.yaml/badge.svg)](https://github.com/NatLabRockies/fastsim/actions/workflows/release.yaml?event=release)
-[![python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10-blue)](https://pypi.org/project/fastsim/)
-[![documentation](https://img.shields.io/badge/documentation-book-blue.svg)](https://natlabrockies.github.io/fastsim/)
-[![github](https://img.shields.io/badge/github-fastsim-blue.svg)](https://github.com/NatLabRockies/fastsim)
+<div style="height: 2rem;"></div>
 
-# Description
-This is the `fastsim-3` version of [NLR's FASTSim](https://www.nlr.gov/transportation/fastsim.html).
-It introduces numerous new enhancements and features, including:
-- ~10x faster! -- when setting `save_interval` to `None`, which means only the state at the last 
-  time step, which includes fuel consumption and/or battery depletion, among other useful 
-  cumulative state variables.  
-- Roughly ~60% reduction in memory consumption (~160 mb in [`fastsim-2`](https://github.com/NatLabRockies/fastsim) 
-  v. 60 mb in [`fastsim-3`](https://github.com/NatLabRockies/fastsim/tree/fastsim-3)
-- object-oriented, hierarchical model structure
-- ability to control granularity of time-resolved data -- e.g. save at every time step, save at 
-  every _n_th time step, or never save at all (saving only cumulative trip-level results)
-- component-specific vehicle models -- i.e. the conventional vehicle contains only data for the fuel
-  converter and other relevant components but does contain any dummy battery or motor parameters as
-  is the case in `fastsim-2`
-- file formats that are more robust and more human readable
-- backwards compatibility with `fastsim-2`
-- flexible data structures to allow for future model types
-- ability to simulate standalone component models
-- flexible model interfacing (e.g. multiple folder/file formats for reading and/or writing data)
-- more accurate interpolation methods
+FASTSim (**Future Automotive Systems Technology Simulator**) is a vehicle simulation tool for evaluating the effects of technology improvements on the efficiency and performance of on-road vehicles, including light-duty passenger cars, two-wheelers, and medium- and heavy-duty vocational vehicles.
 
-# Installation
-
-## Python 
-Set up and activate a python environment (compatible with Python 3.8 - 3.10; we recommend Python 3.10) with the following steps.
+FASTSim is designed for rapid analysis, making it practical to run many
+simulations and compare technology scenarios across vehicle classes and use
+cases. FASTSim outputs also feed other NLR tools, including:
+- [RouteE](https://www.nlr.gov/transportation/route-energy-prediction-model):
+  an energy prediction tool and energy-aware routing engine
+- [T3CO](https://www.nlr.gov/transportation/t3co):
+  a medium- and heavy-duty vehicle total cost of ownership assessment tool
+- [ADOPT](https://www.nlr.gov/transportation/adopt):
+  a technology-driven consumer choice and vehicle market adoption model
 
-### [Anaconda](https://www.anaconda.com/) 
-1. Create: `conda create -n fastsim python=3.10`
-1. Activate: `conda activate fastsim`
+FASTSim models conventional vehicles, hybrids, plug-in hybrids,
+and battery electric vehicles over a set of standard regulatory drive cycles.
+You can also define custom vehicles and custom drive cycles to simulate
+any on-road vehicle over realistic scenarios.
 
-### [venv](https://docs.python.org/3/library/venv.html)
-There is some variation based on your Operating System:  
+For detailed documentation on FASTSim, including usage, background, and modeling philosophy, see https://natlabrockies.github.io/fastsim.
 
-- PowerShell (windows):
-    1. Create: `python -m venv fastsim-venv` -- name is user decision
-    1. Activate: `fastsim-venv/Scripts/Activate.ps1`
+For a collection of prebuilt vehicle models, see the [FASTSim Vehicle Database](https://github.com/NatLabRockies/fastsim-vehicles).
 
-- Bash (i.e. unix/linux/mac):
-    1. Create: `python -m venv fastsim-venv` -- name is user decision
-    1. Activate: `source fastsim-venv/bin/activate`
+# Installation
 
-- Command Prompt (windows):
-    1. Create: `python -m venv fastsim-venv` -- name is user decision
-    1. Activate: `fastsim-venv/Scripts/activate.bat`
+FASTSim is available as a package for use in
+[Python 3.10 through 3.15](https://www.python.org).
 
-### [Pixi](https://pixi.sh/latest/) (recommended for developers)
-1. `pixi shell -e dev` -- this creates the environment, installs all the dependencies,
-    builds fastsim, and activates the environment
+In an active Python environment, run:
 
-## FASTSim-3
-### Via PyPI
-In an active Python environment created above, run `pip install fastsim`.
+```bash
+pip install fastsim
+```
 
-### Building from Scratch
-Developers might want to install the code in place so that FASTSim files can be editable (the `-e` flag for 
-pip provides this behavior). This option can be handy since FASTSim will be installed in place from the 
-installation location and any updates will be propagated each time FASTSim is freshly imported.  To do 
-this, you'll need to have the [Rust toolchain](https://www.rust-lang.org/tools/install) installed.
+This installs the latest FASTSim release as a Python package.
 
-- Option 1: run `sh build_and_test.sh` in root folder.  
-- Option 2:  
-    1. Run `pip install -e ".[dev]"`  
-    Optional testing steps:
-    1. Run `cargo test`
-    1. Run `pytest -v python/fastsim/tests/`
+For more detailed instructions, including compilation of FASTSim from source, see the
+[Installation](https://natlabrockies.github.io/fastsim/installation)
+page of
+[FASTSim's documentation](https://natlabrockies.github.io/fastsim).
 
+## Usage
 
-# Contributors  
-Chad Baker -- Chad.Baker@nrel.gov  
-Aaron Brooker -- Aaron.Brooker@nrel.gov  
-Kyle Carow -- Kyle.Carow@nrel.gov  
-Jeffrey Gonder -- Jeff.Gonder@nrel.gov  
-Jacob Holden -- Jacob.Holden@nrel.gov  
-Jinghu Hu -- Jinghu.Hu@nrel.gov  
-Jason Lustbader -- Jason.Lustbader@nrel.gov  
-Sean Lopp -- sean@rstudio.com  
-Matthew Moniot -- Matthew.Moniot@nrel.gov  
-Grant Payne -- Grant.Payne@nrel.gov  
-Laurie Ramroth -- lramroth@ford.com  
-Eric Wood -- Eric.Wood@nrel.gov
-Robin Steuteville -- Robin.Steuteville@nrel.gov
+For instruction on using FASTSim to simulate on-road vehicle performance, see the
+[User Guide](https://natlabrockies.github.io/user-guide)
+section of
+[FASTSim's documentation](https://natlabrockies.github.io/fastsim).

docs/assets/site.css

@@ -0,0 +1,7 @@
+/* Increase the site header logo size in the MyST book theme. */
+img[src*="edit-nlr-logo-color-horizontal-png-v2"],
+img[src*="edit-nlr-logo"] {
+  height: 55px !important;
+  max-height: 55px !important;
+  width: auto !important;
+}

docs/content/background/related-tools.md

@@ -0,0 +1,34 @@
+# Related Tools
+
+## [RouteE](https://www.nlr.gov/transportation/route-energy-prediction-model)
+
+NLR's **Route Energy Prediction** (RouteE) modeling tools enable vehicle energy estimation and energy-aware route planning.
+
+The open-source RouteE suite consists of two key tools—**RouteE Powertrain** and **RouteE Compass**—along with the simplified RouteE API. 
+
+- ### [RouteE Powertrain](https://github.com/NatLabRockies/routee-powertrain)
+
+    Built as a modular Python package, RouteE Powertrain predicts the energy consumption of a given vehicle over a proposed route. It accounts for various driving conditions such as anticipated traffic congestion, traffic speed, road type, number of lanes, road grade, and turns. It enables users to obtain energy estimates for the full range of vehicle sizes—from light-duty vehicles to heavy-duty trucks and transit buses—for trips or routes where detailed drive cycle data may be unavailable. 
+
+- ### [RouteE Compass](https://github.com/NatLabRockies/routee-compass)
+
+    RouteE Compass is an energy-aware routing tool that incorporates energy consumption predictions from RouteE Powertrain into network routing algorithms. It can accommodate any vehicle size or powertrain technology. RouteE Compass is built as a high-performance Rust application with easy-to-use Python bindings. 
+
+## [T3CO](https://www.nlr.gov/transportation/t3co)
+
+NLR's **Transportation Technology Total Cost of Ownership** (T3CO) tool enables levelized assessments of the full life cycle costs of advanced technology commercial vehicles.
+
+Medium- and heavy-duty commercial vehicles operate in diverse vocations with varied duty cycles, performance, and technical and economic requirements. T3CO accounts for these operational variations as well as advanced technology considerations.
+
+The T3CO methodology, vetted by industry and stakeholders, employs best practices developed across U.S. Department of Energy total cost of ownership studies while addressing key gaps in standard methodologies. 
+
+## [ADOPT](https://www.nlr.gov/transportation/adopt)
+
+NLR's **Automotive Deployment Options Projection Tool** (ADOPT) is a vehicle consumer choice and stock model for light- and heavy-duty vehicles.
+
+ADOPT estimates the impact of vehicle technology improvements on U.S. vehicle sales and energy use. It provides consumer choice estimates based on questions such as:
+
+- How much impact do lower battery prices have on electric vehicle sales?
+- How quickly would the market adopt a co-optimized engine/fuel combination that achieves a 10% efficiency improvement?
+- How do fuel prices impact the electric vehicle/plug-in hybrid electric vehicle sales mix?
+- How does vehicle lightweighting impact powertrain sales?

docs/content/background/what-is-fastsim.md

@@ -0,0 +1,66 @@
+# What is FASTSim?
+
+FASTSim (Future Automotive Systems Technology Simulator) is a high-level
+vehicle simulation tool developed at the [National Laboratory of the Rockies
+(NLR)](https://www.nlr.gov) to support transportation analysis. The tool
+answers common technology-assessment questions quickly, with fewer required
+inputs than high-fidelity physics models.
+
+## History
+
+:::{note}
+This section needs more detailed input
+:::
+
+<!-- FASTSim started as an NLR vehicle powertrain analysis model focused on speed,
+accessibility, and broad scenario coverage. The 2015 SAE paper documents the
+core approach: use high-level component representations and drive-cycle
+simulation to compare powertrains quickly.
+
+NLR's 2021 validation report then formalized FASTSim's modeling philosophy as
+an accuracy-complexity tradeoff, with FASTSim occupying a practical "sweet
+spot" for large batch analysis and real-world cycle studies. -->
+
+Today, the actively maintained [GitHub page](https://github.com/NatLabRockies/fastsim) houses the latest version of the open-source FASTSim Python package, with core logic written in Rust for maximum simulation speed, modeling flexibility, and runtime stability guarantees.
+Releases are made to the [PyPI](https://pypi.org/project/fastsim) (Python Package Index) for easy distribution and installation via `pip`. The [NLR.gov FASTSim homepage](https://www.nlr.gov/transportation/fastsim) distributes the legacy Excel and Python-only versions and describes FASTSim's extensive publication history.
+
+## Modeling Philosophy
+
+FASTSim sits between very simple screening tools and highly detailed component/control models,
+with flexibility to increase model detail when required.
+The core philosophy is to balance:
+
+- Accuracy
+- Input burden and calibration effort
+- Runtime speed
+- Transparency and reproducibility
+
+FASTSim occupies a “sweet spot” along the continuum of modeling tools based on each tool’s
+trade-off between accuracy and complexity, where “complexity” includes the required number of
+input parameters, availability of required input data, time required to obtain the inputs and perform
+calibration, software requirements, and computational overhead to run (Figure ES-1). FASTSim
+is designed to balance predictive accuracy with model complexity across a wide range of analytical
+tasks. Across its range of capabilities, FASTSim is particularly well suited for quickly and
+conveniently conducting large numbers of simulations over representative real-world driving
+distributions and/or myriad vehicle design variations. In such analyses, the uncertainties and
+efficiency impacts from the broad spectrum of operating conditions or design variants far exceed
+small uncertainties resulting from modeling simplifications within FASTSim.
+
+For more information on FASTSim's modeling philosophy and validation against real-world data,
+refer to the [2021 FASTSim Validation Report](https://docs.nlr.gov/docs/fy22osti/81097.pdf).
+
+The validation report compares FASTSim outputs with laboratory and on-road data across
+all modeled powertrains. It shows that:
+
+- Basic FASTSim models perform well for many high-level efficiency and energy studies.
+- Calibrated FASTSim models can closely match second-by-second and trip-level data in
+  targeted calibration efforts.
+
+## Conclusion
+
+Because FASTSim is open source, computationally lightweight, and built for
+large batches of simulations, it is well suited for analyses that need to be
+shared, replicated, and debated across many stakeholders.
+
+Across NLR's suite of analysis software, FASTSim also serves as a core simulation layer that can
+feed downstream tools for routing, cost of ownership, market adoption analysis, and more. For NLR tools related to FASTSim, see [](related-tools.md).

docs/content/developers/compiling-from-source.md

@@ -0,0 +1,13 @@
+# Compiling from Source
+
+First, set up your environment (see [Environment Setup](environment-setup.md)).
+
+To compile FASTSim from source and install into your environment, run:
+```bash
+maturin develop
+```
+
+Or, to compile with optimizations (longer compilation, but faster at runtime):
+```bash
+maturin develop --release
+```