Merge branch 'fastsim-2' into feature/full-feature-for-dependency-red…

…uction

.github/workflows/deploy-book.yaml

@@ -7,6 +7,8 @@ on:
     paths:
       - "docs/**"
       - ".github/workflows/deploy-book.yaml"
+      - "README.md"
+      - "python/**"
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -31,11 +33,24 @@ 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
+
+      - 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}}/fastsim/
+        run:
+          pydoc-markdown -I python/ --render-toc > docs/src/python-doc.md
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v3

README.md

@@ -1,26 +1,28 @@
+# FASTSim
+
 ![FASTSim Logo](https://www.nrel.gov/transportation/assets/images/icon-fastsim.jpg)
 
 [![homepage](https://img.shields.io/badge/homepage-fastsim-blue)](https://www.nrel.gov/transportation/fastsim.html) [![tests](https://github.com/NREL/fastsim/actions/workflows/tests.yaml/badge.svg)](https://github.com/NREL/fastsim/actions/workflows/tests.yaml) [![wheels](https://github.com/NREL/fastsim/actions/workflows/wheels.yaml/badge.svg)](https://github.com/NREL/fastsim/actions/workflows/wheels.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://nrel.github.io/fastsim/) [![github](https://img.shields.io/badge/github-fastsim-blue.svg)](https://github.com/NREL/fastsim)
 
 
-# Description
+## Description
 
 This is the python/rust flavor of [NREL's FASTSim<sup>TM</sup>](https://www.nrel.gov/transportation/fastsim.html), which is based on the original Excel implementation. Effort will be made to keep the core methodology between this software and the Excel flavor in line with one another.
 
 All classes and methods are self-documented.  
 
-# Installation
+## Installation
 
-## Python
+### Python
 
 Set up and activate a python environment (compatible with Python 3.8 - 3.10; we recommend Python 3.10) with the following steps.
 
-### [Anaconda](https://www.anaconda.com/)
+#### [Anaconda](https://www.anaconda.com/)
 
 1. Create: `conda create -n fastsim python=3.10`
 1. Activate: `conda activate fastsim`
 
-### [venv](https://docs.python.org/3/library/venv.html)
+#### [venv](https://docs.python.org/3/library/venv.html)
 
 There is some variation based on your Operating System:  
 
@@ -36,13 +38,13 @@ There is some variation based on your Operating System:
     1. Create: `python -m venv fastsim-venv` -- name is user decision
     1. Activate: `fastsim-venv/Scripts/activate.bat`
 
-## FASTSim
+### FASTSim
 
-### Via PyPI
+#### Via PyPI
 
 In an active Python environment created above, run `pip install fastsim`.
 
-### Building from Scratch
+#### 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.
 
@@ -53,23 +55,23 @@ Developers might want to install the code in place so that FASTSim files can be
     1. Run `cd rust/ && cargo test`
     1. Run `pytest -v python/fastsim/tests/`
 
-# Usage
+## Usage
 
 To see and run examples, navigate to `./python/fastsim/demos` and run the various *demo.py files to see fastsim use cases. There are other examples in fastsim/tests.  
 
-# Adding FASTSim as a Depency in Rust
+## Adding FASTSim as a Depency in Rust
 
-## Via GitHub
+### Via GitHub
 
 Add this line:  
 `fastsim-core = { git = "https://github.nrel.gov/MBAP/fastsim", branch = "rust-port" }`  
 to your Cargo.toml file, modifying the `branch` key as appropriate.  
 
-## Via Cargo
+### Via Cargo
 
 This has not been implemented yet.  
 
-# List of Abbreviations
+## List of Abbreviations
 
 cur = current time step  
 prev = previous time step  
@@ -96,11 +98,11 @@ ach = achieved value
 in = component input  
 out = component output  
 
-# Known Issues
+## Known Issues
 
 Rust versions of classes have limited Language Server Protocol integration, and we are actively working on fixing this.  
 
-# Release Notes
+## Release Notes
 
 2.1.1 -- license changed to Apache 2.0, default cycle grade and road type to zero if not provided, defaults to regenerative braking parameters, optional documentation fields now generated in Rust
 2.1.0 -- release and installation improvements, RustVehicle init cleanup, calibration improvements
@@ -140,7 +142,7 @@ Rust versions of classes have limited Language Server Protocol integration, and
 0.1.2 -- Fixes os-dependency of xlwings by not running stuff that needs xlwings.  Improvements in functional test.  Refinment utomated typying of jitclass objects.
 0.1.1 -- Now includes label fuel economy and/or battery kW-hr/mi values that match excel and test for benchmarking against Excel values and CPU time.
 
-# Contributors  
+## Contributors  
 
 Chad Baker -- <[email protected]>  
 Aaron Brooker -- <[email protected]>  

docs/.gitignore

@@ -1 +1,2 @@
-book/
+book/
+src/python-doc.md

docs/src/SUMMARY.md

@@ -1,4 +1,7 @@
 # Summary
 
 - [Introduction](./intro.md)
+- [Documentation](./fastsim-doc.md)
+    - [Python](./python-doc.md)
+    - [Rust](./rust-doc.md)
 - [How to Update This Book](./how-to-update.md)

docs/src/fastsim-doc.md

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

docs/src/how-to-update.md

@@ -4,12 +4,19 @@
 
 ## Setup
 
-1. If not already done, [install mdbook](https://rust-lang.github.io/mdBook/guide/installation.html)
+If not already done, [install mdbook](https://rust-lang.github.io/mdBook/guide/installation.html)
 
-## Publishing
+## Serving locally
+Run the following in the repository root directory: 
+1. If any python files were modified, 
+    1. Install [pipx](https://github.com/pypa/pipx#install-pipx)
+    1. Install [pydoc-markdown](https://niklasrosenstein.github.io/pydoc-markdown/#installation-)
+    1. run `pydoc-markdown -I python/ --render-toc > docs/src/python-doc.md`. Do not modify this file manually. 
+1. Run `mdbook serve --open docs/`
 
+## Publishing
 1. Update `book.toml` or files in `docs/src/`
-1. Make sure the docs look good locally: `mdbook build docs/ --open`
+1. Make sure the docs look good locally by running the 
 1. Commit files and push to `main` branch
 
-After that, a GitHub action will build the book and publish it [here](https://pages.github.nrel.gov/MBAP/mbap-computing/)
+After that, a GitHub action will build the book and publish it [here](https://pages.github.nrel.gov/MBAP/mbap-computing/)

docs/src/intro.md

@@ -1,6 +1,6 @@
-![FASTSim Logo](https://www.nrel.gov/transportation/assets/images/icon-fastsim.jpg)
 
-[![homepage](https://img.shields.io/badge/homepage-fastsim-blue)](https://www.nrel.gov/transportation/fastsim.html) [![tests](https://github.com/NREL/fastsim/actions/workflows/tests.yaml/badge.svg)](https://github.com/NREL/fastsim/actions/workflows/tests.yaml) [![wheels](https://github.com/NREL/fastsim/actions/workflows/wheels.yaml/badge.svg)](https://github.com/NREL/fastsim/actions/workflows/wheels.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://nrel.github.io/fastsim/) [![github](https://img.shields.io/badge/github-fastsim-blue.svg)](https://github.com/NREL/fastsim)
+{{#include ../../README.md}}
 
+## About this book
 
 This is the overall FASTSim documentation. We're working toward making this a fully integrated document that includes both the Python API and Rust core documentation for the `fastsim-2` branch and eventually also for the `fastsim-3` branch.  

docs/src/rust-doc.md

@@ -0,0 +1,2 @@
+
+# [Rust Documentation](https://docs.rs/fastsim-core/latest/fastsim_core/)

python/fastsim/__init__.py

@@ -9,7 +9,7 @@
 from . import fastsimrust
 from . import fastsimrust as fsr
 from . import parameters as params
-from . import utilities as utils
+from . import utils
 from . import simdrive, vehicle, cycle, calibration, tests
 from . import calibration as cal
 from .resample import resample

python/fastsim/auxiliaries.py

@@ -1,26 +1,29 @@
 """Auxiliary functions that require fastsim and provide faster access FASTSim vehicle properties."""
-import fastsim as fsim
-from fastsim.vehicle import Vehicle
-from fastsim import parameters as params
 from scipy.optimize import minimize, curve_fit
 import numpy as np
 import matplotlib.pyplot as plt
 from typing import Tuple, List
 
-from fastsim.utilities import get_rho_air
+# Local imports
+import fastsim as fsim
+from fastsim.vehicle import Vehicle
+from fastsim import parameters as params
+from fastsim.utils import get_rho_air
 
 props = params.PhysicalProperties()
 R_air = 287  # J/(kg*K)
 
 
-def abc_to_drag_coeffs(veh: Vehicle,
-                       a_lbf: float, b_lbf__mph: float, c_lbf__mph2: float,
-                       custom_rho: bool = False,
-                       custom_rho_temp_degC: float = 20.,
-                       custom_rho_elevation_m: float = 180.,
-                       simdrive_optimize: bool = True,
-                       show_plots: bool = False,
-                       use_rust=True) -> Tuple[float, float]:
+def abc_to_drag_coeffs(
+    veh: Vehicle,
+    a_lbf: float, b_lbf__mph: float, c_lbf__mph2: float,
+    custom_rho: bool = False,
+    custom_rho_temp_degC: float = 20.,
+    custom_rho_elevation_m: float = 180.,
+    simdrive_optimize: bool = True,
+    show_plots: bool = False,
+    use_rust=True
+) -> Tuple[float, float]:
     """For a given vehicle and target A, B, and C
     coefficients; calculate and return drag and rolling resistance
     coefficients.
@@ -41,13 +44,16 @@ def abc_to_drag_coeffs(veh: Vehicle,
     """
 
     # TODO: allows air density read APIs for whole project; `get_rho_air()` not used for `SimDrive` yet
-    cur_ambient_air_density_kg__m3 = get_rho_air(
-        custom_rho_temp_degC, custom_rho_elevation_m) if custom_rho else props.air_density_kg_per_m3
+
+    if custom_rho:
+        cur_ambient_air_density_kg__m3 = get_rho_air(custom_rho_temp_degC, custom_rho_elevation_m)  
+    else:
+        cur_ambient_air_density_kg__m3 = props.air_density_kg_per_m3
 
     vmax_mph = 70.0
 
     a_newton = a_lbf * params.N_PER_LBF
-    b_newton__mps = b_lbf__mph * params.N_PER_LBF * params.MPH_PER_MPS
+    _b_newton__mps = b_lbf__mph * params.N_PER_LBF * params.MPH_PER_MPS
     c_newton__mps2 = c_lbf__mph2 * params.N_PER_LBF * \
         params.MPH_PER_MPS * params.MPH_PER_MPS
 

python/fastsim/demos/demo.py

@@ -41,7 +41,7 @@
 
 # local modules
 import fastsim as fsim
-import fastsim.utilities as utils
+
 # importlib.reload(simdrive) importlib.reload(cycle)
 
 #for testing demo files, false when running automatic tests

python/fastsim/demos/demo_abc_drag_coef_conv.py

@@ -1,6 +1,5 @@
 import fastsim as fsim
 from fastsim.auxiliaries import abc_to_drag_coeffs, drag_coeffs_to_abc
-import fastsim.utilities as utils
 v = fsim.vehicle.Vehicle.from_vehdb(1).to_rust()
 v2 = fsim.vehicle.Vehicle.from_vehdb(1).to_rust()
 

python/fastsim/demos/demo_eu_vehicle_wltp.py

@@ -5,7 +5,7 @@
 import time
 import fastsim as fsim
 import fastsim.parameters as params
-import fastsim.utilities as utils
+import fastsim.utils as utils
 import matplotlib.pyplot as plt
 
 

python/fastsim/demos/fusion_thermal_demo.py

@@ -11,7 +11,6 @@
 from pathlib import Path
 import os
 import sys
-import fastsim.utilities as utils
 
 #for testing demo files, false when running automatic tests
 SHOW_PLOTS = fsim.utils.show_plots()

python/fastsim/demos/stop_start_demo.py

@@ -13,7 +13,6 @@
 import importlib
 import seaborn as sns
 import fastsim as fsim
-import fastsim.utilities as utils
 
 sns.set()
 

python/fastsim/demos/time_dilation_demo.py

@@ -17,7 +17,6 @@
 from fastsim import parameters as params
 
 import fastsim as fsim
-import fastsim.utilities as utils
 
 # importlib.reload(simdrive)
 

python/fastsim/demos/vehicle_import_demo.py

@@ -7,10 +7,10 @@
 import os, pathlib
 
 import fastsim.fastsimrust as fsr
-from fastsim.demos.utils import maybe_str_to_bool, DEMO_TEST_ENV_VAR
+import fastsim.utils as utils
 
-RAN_SUCCESSFULLY = False
-IS_INTERACTIVE = maybe_str_to_bool(os.getenv(DEMO_TEST_ENV_VAR))
+#for testing demo files, false when running automatic tests
+SHOW_PLOTS = utils.show_plots()
 
 # %%
 # Setup some directories
@@ -33,14 +33,14 @@
 # Python pathlib.Path object will be rejected.
 
 options = fsr.get_options_for_year_make_model(year, make, model)
-if IS_INTERACTIVE:
+if SHOW_PLOTS:
     for opt in options:
         print(f"{opt.id}: {opt.transmission}")
 
 # %%
 # Get the data for the given option
 data = options[1]
-if IS_INTERACTIVE:
+if SHOW_PLOTS:
     print(
         f"{data.year} {data.make} {data.model}: {data.comb_mpg_fuel1} mpg ({data.city_mpg_fuel1} CITY / {data.highway_mpg_fuel1} HWY)"
     )
@@ -81,11 +81,6 @@
 # Python pathlib.Path object will be rejected.
 
 vehs = fsr.import_all_vehicles(int(year), make, model, other_inputs)
-if IS_INTERACTIVE:
+if SHOW_PLOTS:
     for v in vehs:
-        print(f"Imported {v.scenario_name}")
-
-
-# %%
-# Used for automated testing
-RAN_SUCCESSFULLY = True
+        print(f"Imported {v.scenario_name}")

python/fastsim/resources/FASTSim_py_veh_db.csv

@@ -58,3 +58,4 @@ selection,Scenario name,veh_year,veh_pt_type,drag_coef,frontal_area_m2,glider_kg
 57,2021 Honda N-Box G,2021,Conv,0.38,2.19,0,0.53,0.61,2.52,0,1050,2000,1.1,239.27,9.89,43,,SI,6.1,0,2.13,,0,4.8,FALSE,0,0,0,0,0,0,1,110.8,-0.6811,0.815,4,0.0101,0.27855,0.8,0,1,0,0,60.3,0.2,0.8,55.8,100.8,1,0.86,0.7,FALSE,114.9,0.95,1.4,0.005,0.98,,,,,,,,,,,,,,17.1,,,,,30.3,0,
 58,2021 BMW iX xDrive40,2021,BEV,0.25,2.82,0,-0.53,0.61,3,0,2600,0,1.1,0,0,0,,SI,6.1,0,0,,240,4.8,FALSE,0.833,21.6,1000,76.6,8.9,75,0.97,110.8,-0.6811,0.815,4,0.0101,0.395,0.8,0.04,0.96689295039,0,0,60.3,0.2,0.8,55.8,100.8,1,0.86,0.25,FALSE,114.9,0.98,1.4,0.005,0.98,,,,,,,,,,,,,,5.5,,,,,30.3,0,
 59,2021 Cupra Born,2021,BEV,0.27,2.31,0,-0.53,0.61,2.766,0,1927,0,1.1,0,0,0,,SI,6.1,0,0,,150,4.8,FALSE,0.833,21.6,1000,82,8.9,75,0.97,110.8,-0.6811,0.815,4,0.011,0.3488,0.8,0.04,0.97902439024,0,0,60.3,0.2,0.8,55.8,100.8,1,0.86,0.25,FALSE,114.9,0.98,1.4,0.005,0.98,,,,,,,,,,,,,,6.8,,,,,30.3,0,
+60,2023 Volvo C40 Recharge,2023,BEV,0.319,2.54,0,0.53,0.61,2.702,0,2620,0,1.1,0,0,0,,SI,6.1,0,0,,299.771,4.8,FALSE,0.833,21.6,1000,78,8.9,75,0.97,110.8,-0.6811,0.815,4,0.0101,0.356,0.8,0.02,0.98153846153,0.3,0.3,60.3,0.2,0.8,55.8,100.8,1,0.86,0.25,FALSE,114.9,0.98,1.4,0.005,0.98,,,,,,,,,,,,,,4.7,,,,,30.3,0,