Struct Cycle

#[non_exhaustive]
pub struct Cycle {
    pub name: String,
    pub init_elev: Option<Length>,
    pub time: Vec<Time>,
    pub speed: Vec<Velocity>,
    pub dist: Vec<Length>,
    pub grade: Vec<Ratio>,
    pub elev: Vec<Length>,
    pub pwr_max_chrg: Vec<Power>,
    pub temp_amb_air: Vec<Temperature>,
    pub pwr_solar_load: Vec<Power>,
    pub grade_interp: Option<InterpolatorEnumOwned<f64>>,
    pub elev_interp: Option<InterpolatorEnumOwned<f64>>,
}

Container

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: String

Name of cycle (can be left empty)

init_elev: Option<Length>

inital elevation

time: Vec<Time>

simulation time

speed: Vec<Velocity>

prescribed speed

dist: Vec<Length>

calculated prescribed distance based on RHS integral of time and speed

grade: Vec<Ratio>

road grade (expressed as a decimal, not percent)

elev: Vec<Length>

calculated prescribed elevation based on RHS integral distance and grade

pwr_max_chrg: Vec<Power>

road charging/discharing capacity

temp_amb_air: Vec<Temperature>

ambient air temperature w.r.t. to time (rather than spatial position)

pwr_solar_load: Vec<Power>

solar heat load w.r.t. to time (rather than spatial position)

grade_interp: Option<InterpolatorEnumOwned<f64>>

grade interpolator

elev_interp: Option<InterpolatorEnumOwned<f64>>

elevation interpolator

Implementations

impl Cycle

pub fn dt_at_i(&self, i: usize) -> Result<Time>

rust-internal time steps at i

pub fn len_checked(&self) -> Result<usize>

return the length of the cycle

pub fn is_empty(&self) -> Result<bool>

return true if the cycle is empty, else false

pub fn push(&mut self, element: CycleElement) -> Result<()>

append the given cycle element

pub fn extend(&mut self, vec: Vec<CycleElement>) -> Result<()>

extend the cycle by a vector of elements

pub fn trim( &mut self, start_idx: Option<usize>, end_idx: Option<usize>, ) -> Result<()>

trim the cycle to the given start_idx and end_idx.

NOTE: ending cycle will include start_idx but NOT end_idx

pub fn to_csv(&self) -> Result<String>

Write (serialize) cycle to a CSV string

pub fn to_fastsim2(&self) -> Result<Cycle2>

pub fn to_elements(&self) -> Vec<CycleElement>

convert cycle to a vector of CycleElement

pub fn to_microtrips(&self, stop_speed: Option<Velocity>) -> Vec<Cycle>

Convert cycle into a vector of “microtrips”. A microtrip is a start to a subsequent stop plus any idle time.

• stop_speed: the speed at or below which vehicle is considered “stopped”

RETURN: vector of cycles with each cycle being a “microtrip”.

pub fn average_speed(&self, while_moving: bool) -> Velocity

Determine average speed of cycle. – while_moving: if true, only takes average while moving

RETURN: average speed

pub fn average_step_speeds(&self) -> Vec<Velocity>

Return the average step speeds of the cycle as vector of velicities. NOTE: the average speed from sample i-1 to i will appear as entry i. RETURN: vector of velocities representing average step speeds.

pub fn average_step_speed_at(&self, i: usize) -> Velocity

Calculate the average step speed at step i (i.e., from sample point i-1 to i)

pub fn trapz_step_distances(&self) -> Vec<Length>

The distances traveled over each step using trapezoidal integration.

pub fn trapz_step_elevations(&self) -> Vec<Length>

The elevation climb each step using trapezoidal integration.

pub fn trapz_step_start_distance(&self, step: usize) -> Length

The distance traveled from start to the beginning of step i (i.e., distance traveled up to sample point i-1)

pub fn trapz_distance_for_step(&self, step: usize) -> Length

The distance traveled during the given step (i.e., distance from sample point i-1 to i for step i)

pub fn trapz_distance_over_range(&self, step0: usize, step1: usize) -> Length

Calculate the distance from step i_start to the start of step i_end (i.e., distance from sample point i_start - 1 to i_end - 1)

pub fn time_spent_moving(&self, stopped_speed: Option<Velocity>) -> Time

Calculate the time in a cycle spent moving

• stopped_speed_m_per_s: the speed above which we are considered to be moving

RETURN: the time spent moving in seconds

pub fn distance_and_target_speeds_by_microtrip( &self, stop_speed: Option<Velocity>, blend_factor: f64, min_target_speed: Velocity, ) -> Vec<(Length, Velocity)>

Create distance and target speeds by microtrip. Splits cycle into microtrips and returns a list of 2-tuples of: (distance from start in meters, target speed in m/s) The distance is measured to the start of the microtrip.

Parameters

• blend_factor: from 0.0 to 1.0
  • if 0.0, use the average speed of the microtrip
  • if 1.0, use the average speed while moving (i.e., no stopped time)
  • otherwise, something in between
• min_target_speed: the minimum target speed allowed

Result

List of 2-tuple of (distance from start, target speed). A tuple represents the distance from start of the start of the given microtrip and its target speed.

Notes

• target speed per microtrip is not allowed to be below the min_target_speed

pub fn extend_time( &self, absolute_time: Option<Time>, time_fraction: Option<Ratio>, ) -> Cycle

Add idle time to Cycle. By “idle” time, we mean “stopped” time (i.e., vehicle not moving).

pub fn build_cache(&self) -> CycleCache

Create a cache object for faster computations on Cycle.

pub fn average_grade_over_range( &self, distance_start: Length, delta_distance: Length, cache: Option<&CycleCache>, ) -> Ratio

Returns the average grade over the given range of distances.

• distance_start: the distance at start of evaluation area
• delta_distance: distance traveled from distance_start
• cache: optional CycleCache which can save computation time

RETURN: average grade (rise over run) for the given range.

NOTE: grade is assumed to be constant from just after the previous sample point until the current sample point (inclusive). That is, grade[i] applies from distance, d, of (d[i - 1], d[i]]

pub fn calc_distance_to_next_stop_from( &self, distance: Length, cache: Option<&CycleCache>, ) -> Length

Calculate the distance to next stop from distance.

• distance: the distance to calculate distance-to-stop from

RETURN: returns the distance to the next stop from distance

NOTE: distance may be negative if we’re beyond the last stop

pub fn modify_by_const_jerk_trajectory( &mut self, i: usize, n: usize, jerk: Jerk, accel0: Acceleration, ) -> Velocity

Modify the cycle using the given constant-jerk trajectory.

• i: the index into the cycle to initiate modification NOTE: THIS point is modified as trajectory is calculated as starting at i-1
• n: the number of steps ahead
• jerk: the jerk (deriviative of acceleration with time)
• accel0: the starting accelartion

NOTE:

• modifies the cycle in-place. Purpose is to allow hitting a rendezvous point in time/speed in the future.
• CAUTION: not robust against variable duration time-steps

RETURN: the final modified speed

pub fn modify_with_braking_trajectory( &mut self, brake_accel: Acceleration, i: usize, desired_distance_to_stop: Option<Length>, ) -> (Velocity, usize)

Modify cycle to add a braking trajectory that would cover the same distance as the given constant brake deceleration.

• brake_accel: the brake acceleration (m/s2); must be negative
• i: index where to initiate the stop trectory; start of the step
• desired_distance_to_stop: the desired distance to stop within. If not provided, it is calculated based on the braking deceleration.

RETURN: (final speed of modified trajectory, number of steps to complete)

• the final speed should be zero ideally
• the number of time-steps required to complete the braking maneuver

NOTE:

• modifies the cycle in-place.

pub fn ending_idle_time(&self) -> Time

Report the stopped time (i.e., idle) at the end of a cycle.

RESULT: time vehicle is at zero speed at cycle end

pub fn trim_ending_idle(&self, idle_to_keep: Option<Time>) -> Cycle

Remove idel time at end of cycle except for the optionally specified duration.

• idle_to_keep: optional duration of idle time to keep. Default is 0 s

RESULT: a new cycle with idle time trimmed.

pub fn resample(&self, dt: Time) -> Cycle

Resample cycle to a lower or higher frequency.

• dt: the new step duration.

RETURN: cycle NOTE: a value of dt <= 0 s implies to just clone the current cycle “as is”

Trait Implementations

impl Clone for Cycle

fn clone(&self) -> Cycle

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cycle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Cycle

fn default() -> Cycle

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Cycle

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Init for Cycle

fn init(&mut self) -> Result<(), Error>

Sets self.dist and self.elev

Assumptions

• if init_elev.is_none(), then defaults to [static@ELEV_DEFAULT]

impl PartialEq for Cycle

fn eq(&self, other: &Cycle) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl SerdeAPI for Cycle

fn to_writer<W: Write>(&self, wtr: W, format: &str) -> Result<(), Error>

Write (serialize) an object into anything that implements std::io::Write

Arguments:

• wtr - The writer into which to write object data
• format - The target format, any of those listed in ACCEPTED_BYTE_FORMATS

fn from_reader<R: Read>( rdr: &mut R, format: &str, skip_init: bool, ) -> Result<Self, Error>

Deserialize an object from anything that implements std::io::Read

Arguments:

• rdr - The reader from which to read object data
• format - The source format, any of those listed in ACCEPTED_BYTE_FORMATS

fn to_str(&self, format: &str) -> Result<String>

Write (serialize) an object into a string

Arguments:

• format - The target format, any of those listed in ACCEPTED_STR_FORMATS

fn from_str<S: AsRef<str>>( contents: S, format: &str, skip_init: bool, ) -> Result<Self>

Read (deserialize) an object from a string

Arguments:

• contents - The string containing the object data
• format - The source format, any of those listed in ACCEPTED_STR_FORMATS

const ACCEPTED_BYTE_FORMATS: &'static [&'static str]

const ACCEPTED_STR_FORMATS: &'static [&'static str]

const RESOURCES_SUBDIR: &'static str = "cycles"

const RESOURCES_DIR: &'static Dir<'_> = _

fn from_resource<P: AsRef<Path>>( filepath: P, skip_init: bool, ) -> Result<Self, Error>

Read (deserialize) an object from a resource file packaged with the fastsim-core crate

fn list_resources() -> Result<Vec<PathBuf>, Error>

List the available resources in the resources directory

fn to_file<P: AsRef<Path>>(&self, filepath: P) -> Result<(), Error>

Write (serialize) an object to a file. Supported file extensions are listed in ACCEPTED_BYTE_FORMATS. Creates a new file if it does not already exist, otherwise truncates the existing file.

fn from_file<P: AsRef<Path>>( filepath: P, skip_init: bool, ) -> Result<Self, Error>

Read (deserialize) an object from a file. Supported file extensions are listed in ACCEPTED_BYTE_FORMATS.

fn to_json(&self) -> Result<String>

Write (serialize) an object to a JSON string

fn from_json<S: AsRef<str>>(json_str: S, skip_init: bool) -> Result<Self>

Read (deserialize) an object from a JSON string

fn to_msg_pack(&self) -> Result<Vec<u8>>

Write (serialize) an object to a message pack

fn from_msg_pack(msg_pack: &[u8], skip_init: bool) -> Result<Self>

Read (deserialize) an object from a message pack

fn to_toml(&self) -> Result<String>

Write (serialize) an object to a TOML string

fn from_toml<S: AsRef<str>>(toml_str: S, skip_init: bool) -> Result<Self>

Read (deserialize) an object from a TOML string

fn to_yaml(&self) -> Result<String>

Write (serialize) an object to a YAML string

fn from_yaml<S: AsRef<str>>(yaml_str: S, skip_init: bool) -> Result<Self>

Read (deserialize) an object from a YAML string

impl Serialize for Cycle

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Cycle