Skip to main content

tpt_sci_ode/
trajectory.rs

1//! A named, time-indexed trajectory with CSV output.
2//!
3//! [`Trajectory`] is the uniform output shape for dense ODE solutions: one row
4//! per output time, one named column per state variable. It is plain data, so
5//! it can be inspected, plotted, or written out with [`Trajectory::to_csv`].
6
7use std::fmt::Write as _;
8use std::io;
9
10use crate::error::OdeError;
11use crate::problem::OdeProblem;
12use crate::solver::Method;
13
14/// Time-indexed states with a name per state variable.
15///
16/// Invariants (enforced by [`Trajectory::new`]): `t.len() == y.len()`, and every
17/// row of `y` has `names.len()` entries.
18#[derive(Debug, Clone, PartialEq)]
19#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
20pub struct Trajectory {
21    /// Output times, in the order they were produced.
22    pub t: Vec<f64>,
23    /// Column names, one per state variable.
24    pub names: Vec<String>,
25    /// `y[k]` is the state at `t[k]`.
26    pub y: Vec<Vec<f64>>,
27}
28
29impl Trajectory {
30    /// Build a trajectory, validating that the shapes agree.
31    ///
32    /// # Errors
33    ///
34    /// Returns [`OdeError::Invalid`] if `t` and `y` differ in length, or if any
35    /// state row does not have one entry per name.
36    pub fn new(t: Vec<f64>, names: Vec<String>, y: Vec<Vec<f64>>) -> Result<Self, OdeError> {
37        if t.len() != y.len() {
38            return Err(OdeError::invalid(format!(
39                "trajectory has {} times but {} states",
40                t.len(),
41                y.len()
42            )));
43        }
44        if let Some((k, row)) = y.iter().enumerate().find(|(_, r)| r.len() != names.len()) {
45            return Err(OdeError::invalid(format!(
46                "state row {k} has {} entries, expected {}",
47                row.len(),
48                names.len()
49            )));
50        }
51        Ok(Self { t, names, y })
52    }
53
54    /// Number of output rows.
55    #[must_use]
56    pub fn len(&self) -> usize {
57        self.t.len()
58    }
59
60    /// Whether the trajectory has no rows.
61    #[must_use]
62    pub fn is_empty(&self) -> bool {
63        self.t.is_empty()
64    }
65
66    /// The values of one named state variable across all rows, or `None` if no
67    /// column has that name.
68    #[must_use]
69    pub fn column(&self, name: &str) -> Option<Vec<f64>> {
70        let idx = self.names.iter().position(|n| n == name)?;
71        Some(self.y.iter().map(|row| row[idx]).collect())
72    }
73
74    /// Render as CSV: a `t` column followed by one column per state variable,
75    /// one row per output time, with a header line. Numbers use Rust's
76    /// shortest round-trip `Display` form.
77    #[must_use]
78    pub fn to_csv(&self) -> String {
79        let mut out = String::new();
80        out.push('t');
81        for name in &self.names {
82            out.push(',');
83            out.push_str(&escape_csv_field(name));
84        }
85        out.push('\n');
86        for (t, row) in self.t.iter().zip(&self.y) {
87            // Writing to a `String` cannot fail.
88            let _ = write!(out, "{t}");
89            for v in row {
90                let _ = write!(out, ",{v}");
91            }
92            out.push('\n');
93        }
94        out
95    }
96
97    /// Write the CSV form (see [`Trajectory::to_csv`]) to any writer.
98    ///
99    /// # Errors
100    ///
101    /// Propagates any I/O error from `writer`.
102    pub fn write_csv<W: io::Write>(&self, mut writer: W) -> io::Result<()> {
103        writer.write_all(self.to_csv().as_bytes())
104    }
105}
106
107impl OdeProblem {
108    /// Integrate and return the dense output as a named [`Trajectory`].
109    ///
110    /// `names` must have one entry per state variable. Output is produced at each
111    /// point of `t_eval` (see [`OdeProblem::solve_dense`]).
112    ///
113    /// # Errors
114    ///
115    /// Returns [`OdeError::Invalid`] if `names` does not match the state size,
116    /// or any error from the integration itself.
117    pub fn solve_trajectory(
118        &self,
119        method: Method,
120        t_eval: &[f64],
121        names: &[&str],
122    ) -> Result<Trajectory, OdeError> {
123        if names.len() != self.nstates() {
124            return Err(OdeError::invalid(format!(
125                "{} names given for {} state variables",
126                names.len(),
127                self.nstates()
128            )));
129        }
130        let y = self.solve_dense(method, t_eval)?;
131        let names = names.iter().map(|n| (*n).to_string()).collect();
132        Trajectory::new(t_eval.to_vec(), names, y)
133    }
134}
135
136/// Quote a CSV field if it contains a delimiter, quote, or newline.
137fn escape_csv_field(field: &str) -> String {
138    if field.contains([',', '"', '\n', '\r']) {
139        format!("\"{}\"", field.replace('"', "\"\""))
140    } else {
141        field.to_string()
142    }
143}
144
145#[cfg(test)]
146mod tests {
147    use super::*;
148
149    fn sample() -> Trajectory {
150        Trajectory::new(
151            vec![0.0, 0.5],
152            vec!["x".into(), "a,b".into()],
153            vec![vec![1.0, 2.0], vec![3.0, 4.5]],
154        )
155        .unwrap()
156    }
157
158    #[test]
159    fn csv_has_header_and_one_row_per_time() {
160        let csv = sample().to_csv();
161        assert_eq!(csv, "t,x,\"a,b\"\n0,1,2\n0.5,3,4.5\n");
162    }
163
164    #[test]
165    fn column_lookup_by_name() {
166        let tr = sample();
167        assert_eq!(tr.column("x"), Some(vec![1.0, 3.0]));
168        assert_eq!(tr.column("missing"), None);
169    }
170
171    #[test]
172    fn rejects_mismatched_shapes() {
173        let bad_len = Trajectory::new(vec![0.0], vec!["x".into()], vec![]);
174        assert!(bad_len.is_err());
175        let bad_row = Trajectory::new(vec![0.0], vec!["x".into()], vec![vec![1.0, 2.0]]);
176        assert!(bad_row.is_err());
177    }
178
179    #[test]
180    fn write_csv_matches_to_csv() {
181        let tr = sample();
182        let mut buf = Vec::new();
183        tr.write_csv(&mut buf).unwrap();
184        assert_eq!(String::from_utf8(buf).unwrap(), tr.to_csv());
185    }
186}