Merge pull request #141 from NREL/fix/issue-348-doc-strings

Add docstrings to RustSimDriveParams

.github/workflows/tests.yaml

@@ -10,6 +10,7 @@ jobs:
   test:
       runs-on: ubuntu-latest
 
+
       strategy:
         fail-fast: true
         matrix:

README.md

@@ -110,51 +110,6 @@ ach = achieved value
 in = component input  
 out = component output  
 
-## Known Issues
-
-Rust versions of classes have limited Language Server Protocol integration, and we are actively working on fixing this.  
-
-## Release Notes
-
-2.1.2 -- SerdeAPI revamp with many new functions, various new vehicles, calibration demo, better error propagation, demo testing
-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
-2.0.11 - 2.0.22 -- PyPI fixes.  Also, Rust version is now >100x faster than Python version.
-2.0.10 -- logging fixes, proc macro reorganization, some CAVs performance fixes  
-2.0.9 -- support for mac ARM/RISC architecture  
-2.0.8 -- performance improvements  
-2.0.6 -- `dist_v2_m` fixes and preliminary CAV functionality  
-2.0.5 -- added `to_rust` method for cycle  
-2.0.4 -- exposed `veh.set_veh_mass`  
-2.0.3 -- exposed `veh.__post_init__`  
-2.0.2 -- provisioned for non-default vehdb path  
-2.0.1 -- bug fix  
-2.0.0 -- All second-by-second calculations are now implemented in both rust and python.  Rust provides a ~30x speedup  
-1.3.1 -- `fastsim.simdrive.copy_sim_drive` function can deepcopy jit to non-jit (and back) for pickling  
-1.2.6 -- time dilation bug fix for zero speed  
-1.2.4 -- bug fix changing `==` to `=`  
-1.2.3 -- `veh_file` can be passed as standalone argument.  `fcEffType` can be anything if `fcEffMap` is provided, but typing is otherwise enforced.  
-1.2.2 -- added checks for some conflicting vehicle parameters.  Vehicle parameters `fcEffType` and `vehPtType` must now be str type.  
-1.2.1 -- improved time dilation and added test for it  
-1.1.7 -- get_numba_veh() and get_numba_cyc() can now be called from already jitted objects  
-1.1.6 -- another bug fix for numba compatibility with corresponding unit test  
-1.1.5 -- bug fix for numba compatibility of fcPeakEffOverride and mcPeakEffOverride  
-1.1.4 -- nan bug fix for fcPeakEffOverride and mcPeakEffOverride  
-1.1.3 -- provisioned for optional load time motor and engine peak overrides  
-1.1.2 -- made vehicle loading _more_ more robust  
-1.1.1 -- made vehicle loading more robust  
-1.1.0 -- separated jitclasses into own module, made vehicle engine and motor efficiency setting more robust  
-1.0.4 -- bug fix with custom engine curve  
-1.0.3 -- bug fixes, faster testing  
-1.0.2 -- forced type np.float64 on vehicle mass attributes  
-1.0.1 -- Added `vehYear` attribute to vehicle and other minor changes.
-1.0.0 -- Implemented unittest package.  Fixed energy audit calculations to be based on achieved speed.  Updated this file.  Improved documentation.  Vehicle can be instantiated as dict.
-0.1.5 -- Updated to be compatible with ADOPT
-0.1.4 -- Bug fix: `mcEffMap` is now robust to having zero as first element
-0.1.3 -- Bug fix: `fastsim.vehicle.Vehicle` method `set_init_calcs` no longer overrides `fcEffMap`.
-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  
 
 Chad Baker -- <[email protected]>  

docs/src/SUMMARY.md

@@ -6,3 +6,4 @@
     - [Rust](./rust-doc.md)
 - [Calibration/Validation](./cal_and_val.md)
 - [How to Update This Book](./how-to-update.md)
+- [Release Notes](./release-notes.md)

docs/src/release-notes.md

@@ -0,0 +1,41 @@
+## Release Notes
+
+2.1.2 -- SerdeAPI revamp with many new functions, various new vehicles, calibration demo, better error propagation, demo testing
+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
+2.0.11 - 2.0.22 -- PyPI fixes.  Also, Rust version is now >100x faster than Python version.
+2.0.10 -- logging fixes, proc macro reorganization, some CAVs performance fixes  
+2.0.9 -- support for mac ARM/RISC architecture  
+2.0.8 -- performance improvements  
+2.0.6 -- `dist_v2_m` fixes and preliminary CAV functionality  
+2.0.5 -- added `to_rust` method for cycle  
+2.0.4 -- exposed `veh.set_veh_mass`  
+2.0.3 -- exposed `veh.__post_init__`  
+2.0.2 -- provisioned for non-default vehdb path  
+2.0.1 -- bug fix  
+2.0.0 -- All second-by-second calculations are now implemented in both rust and python.  Rust provides a ~30x speedup  
+1.3.1 -- `fastsim.simdrive.copy_sim_drive` function can deepcopy jit to non-jit (and back) for pickling  
+1.2.6 -- time dilation bug fix for zero speed  
+1.2.4 -- bug fix changing `==` to `=`  
+1.2.3 -- `veh_file` can be passed as standalone argument.  `fcEffType` can be anything if `fcEffMap` is provided, but typing is otherwise enforced.  
+1.2.2 -- added checks for some conflicting vehicle parameters.  Vehicle parameters `fcEffType` and `vehPtType` must now be str type.  
+1.2.1 -- improved time dilation and added test for it  
+1.1.7 -- get_numba_veh() and get_numba_cyc() can now be called from already jitted objects  
+1.1.6 -- another bug fix for numba compatibility with corresponding unit test  
+1.1.5 -- bug fix for numba compatibility of fcPeakEffOverride and mcPeakEffOverride  
+1.1.4 -- nan bug fix for fcPeakEffOverride and mcPeakEffOverride  
+1.1.3 -- provisioned for optional load time motor and engine peak overrides  
+1.1.2 -- made vehicle loading _more_ more robust  
+1.1.1 -- made vehicle loading more robust  
+1.1.0 -- separated jitclasses into own module, made vehicle engine and motor efficiency setting more robust  
+1.0.4 -- bug fix with custom engine curve  
+1.0.3 -- bug fixes, faster testing  
+1.0.2 -- forced type np.float64 on vehicle mass attributes  
+1.0.1 -- Added `vehYear` attribute to vehicle and other minor changes.
+1.0.0 -- Implemented unittest package.  Fixed energy audit calculations to be based on achieved speed.  Updated this file.  Improved documentation.  Vehicle can be instantiated as dict.
+0.1.5 -- Updated to be compatible with ADOPT
+0.1.4 -- Bug fix: `mcEffMap` is now robust to having zero as first element
+0.1.3 -- Bug fix: `fastsim.vehicle.Vehicle` method `set_init_calcs` no longer overrides `fcEffMap`.
+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.
+

pyproject.toml

@@ -20,7 +20,7 @@ classifiers = [
 dependencies = [
     "pandas>=1",
     "matplotlib>=3.3",
-    "numpy>=1.18",
+    "numpy>=1.18,<1.24",
     "scipy",
     "seaborn>=0.10",
     "typing_extensions",

python/fastsim/demos/time_dilation_demo.py

@@ -42,10 +42,11 @@
 
 sd_fixed = simdrive.SimDrive(cyc, veh)
 sim_params = sd_fixed.sim_params
+# activate time dilation (aka missed trace correction)
 sim_params.missed_trace_correction=True
-# sim_params.min_time_dilation = 1
+# by setting `sim_params.max_time_dilation = 0.1`, we're ensuring that a simulation with 1 s
+# time steps will never exceed a 1.1 s time step to achieve trace matching
 sim_params.max_time_dilation = 0.1
-# sim_params.time_dilation_tol = 1e-1
 
 sd_base = simdrive.SimDrive(cyc, veh)
 

rust/fastsim-core/src/simdrive.rs

@@ -19,37 +19,75 @@ pub mod simdrive_iter;
 )]
 /// Struct containing time trace data
 pub struct RustSimDriveParams {
+    /// if true, accuracy will be favored over performance for grade per step estimates
+    /// Specifically, for performance, grade for a step will be assumed to be the grade
+    /// looked up at step start distance. For accuracy, the actual elevations will be
+    /// used. This distinciton only makes a difference for CAV maneuvers.
     pub favor_grade_accuracy: bool,
-    pub missed_trace_correction: bool, // if true, missed trace correction is active, default = false
+    /// if true, missed trace correction is active, default = False.  If missed
+    /// trace correction is active, time step will be "dilated" to be long enough for
+    /// vehicle to "catch up" with trace.
+    pub missed_trace_correction: bool,
+    /// maximum time dilation factor to "catch up" with trace -- e.g. 1.0 means 100% increase in step size
     pub max_time_dilation: f64,
+    /// minimum time dilation margin to let trace "catch up" -- e.g. -0.5 means 50% reduction in step size
     pub min_time_dilation: f64,
+    /// convergence criteria for time dilation in iterating on time step size to achieve distance parity
     pub time_dilation_tol: f64,
+    /// number of iterations to achieve time dilation correction
     pub max_trace_miss_iters: u32,
+    /// threshold of error in speed [m/s] that triggers warning
     pub trace_miss_speed_mps_tol: f64,
+    /// threshold for printing warning when time dilation is active
     pub trace_miss_time_tol: f64,
+    /// threshold of fractional eror in distance that triggers warning
     pub trace_miss_dist_tol: f64,
+    /// max allowable number of HEV SOC iterations
     pub sim_count_max: usize,
+    /// newton solver gain
     pub newton_gain: f64,
+    /// newton solver max iterations
     pub newton_max_iter: u32,
+    /// newton solver tolerance
     pub newton_xtol: f64,
+    /// tolerance for energy audit error warning, i.e. 0.1%
     pub energy_audit_error_tol: f64,
+    // Eco-Coasting Maneuver Parameters
+    /// if true, coasting to stops are allowed
     pub coast_allow: bool,
+    /// if true, coasting vehicle can eclipse the shadow trace (i.e., reference vehicle in front)
     pub coast_allow_passing: bool,
+    /// maximum allowable speed under coast (m/s)
     pub coast_max_speed_m_per_s: f64,
+    /// acceleration assumed during braking for coast maneuvers (m/s2). note: should be negative
     pub coast_brake_accel_m_per_s2: f64,
+    /// speed when friction braking will initiate during coasting maneuvers (m/s)
     pub coast_brake_start_speed_m_per_s: f64,
+    /// initiates coast when vehicle hits this speed if > 0; this is mainly for forceing coasting to initiate for testing. (m/s)
     pub coast_start_speed_m_per_s: f64,
+    /// "look-ahead" time for speed changes to be considered to feature coasting to hit a given stopping distance mark (s)
     pub coast_time_horizon_for_adjustment_s: f64,
-    pub idm_allow: bool,
     // IDM - Intelligent Driver Model, Adaptive Cruise Control version
+    /// if true, initiates the IDM - Intelligent Driver Model, Adaptive Cruise Control version
+    pub idm_allow: bool,
+    /// IDM algorithm: desired speed (m/s)
     pub idm_v_desired_m_per_s: f64,
+    /// IDM algorithm: headway time desired to vehicle in front (s)
     pub idm_dt_headway_s: f64,
+    /// IDM algorithm: minimum desired gap between vehicle and lead vehicle (m)
     pub idm_minimum_gap_m: f64,
+    /// IDM algorithm: delta parameter
     pub idm_delta: f64,
+    /// IDM algorithm: acceleration parameter
     pub idm_accel_m_per_s2: f64,
+    /// IDM algorithm: deceleration parameter
     pub idm_decel_m_per_s2: f64,
+    /// IDM algorithm: a way to specify desired speed by course distance
+    /// traveled. Can simulate changing speed limits over a driving cycle
+    /// optional list of (distance (m), desired speed (m/s))
     pub idm_v_desired_in_m_per_s_by_distance_m: Option<Vec<(f64, f64)>>,
     // Other, Misc.
+    /// EPA fuel economy adjustment parameters; maximum EPA adjustment factor
     pub max_epa_adj: f64,
     #[serde(skip)]
     pub orphaned: bool,
@@ -80,7 +118,7 @@ impl Default for RustSimDriveParams {
         let newton_max_iter = 100; // newton solver max iterations
         let newton_xtol = 1e-9; // newton solver tolerance
         let energy_audit_error_tol = 0.002; // tolerance for energy audit error warning, i.e. 0.1%
-                                                 // Coasting
+                                            // Coasting
         let coast_allow = false;
         let coast_allow_passing = false;
         let coast_max_speed_m_per_s = 40.0;