Skip to main content

powerio_matrix/io/
mtx.rs

1//! Matrix Market I/O.
2//!
3//! `sprs::io::write_matrix_market_sym` writes the *upper* triangle, but the
4//! Matrix Market spec calls for the *lower* triangle (i ≥ j). To stay
5//! compatible with strict readers (e.g. `fast_matrix_market`), we hand roll
6//! the symmetric writer. We delegate to `sprs` for general (non symmetric)
7//! output and for reading.
8
9use std::io::Write;
10use std::path::Path;
11
12use sprs::CsMat;
13
14use crate::{Error, Result};
15
16pub fn emit_mtx(matrix: &CsMat<f64>, path: impl AsRef<Path>) -> Result<()> {
17    commit_one_file(path.as_ref(), to_mtx_bytes(matrix)?)
18}
19
20/// The complete Matrix Market text for one matrix, symmetric when the header
21/// round trips exactly and general otherwise.
22pub fn to_mtx_bytes(matrix: &CsMat<f64>) -> Result<Vec<u8>> {
23    if is_exactly_symmetric(matrix) {
24        symmetric_mtx_bytes(matrix)
25    } else {
26        general_mtx_bytes(matrix)
27    }
28}
29
30/// Commit one complete file through the no-replace destination: the bytes are
31/// staged and moved onto `path` only when no entry exists there, so a refused
32/// write leaves the caller's filesystem as it was.
33pub(crate) fn commit_one_file(path: &Path, bytes: Vec<u8>) -> Result<()> {
34    // A one file destination takes its target from the caller's path; the
35    // artifact name is a fixed placeholder, so the portability rule governs
36    // inventory names and never which operating system path a caller may
37    // choose.
38    let artifact = powerio_core::MemoryArtifact::new(
39        powerio_core::ArtifactPath::new("case").expect("static placeholder name"),
40        bytes,
41    );
42    powerio_core::Destination::path(path).__commit_artifacts(
43        false,
44        powerio_core::Fidelity::Canonical,
45        vec![artifact],
46        Vec::new(),
47    )?;
48    Ok(())
49}
50
51fn symmetric_mtx_bytes(matrix: &CsMat<f64>) -> Result<Vec<u8>> {
52    let mut w = Vec::new();
53    writeln!(w, "%%MatrixMarket matrix coordinate real symmetric")?;
54    writeln!(w, "% written by powerio")?;
55
56    // Two-pass: count entries first so the header can carry the exact nnz.
57    let nnz = matrix
58        .iter()
59        .filter(|&(_, (i, j))| i >= j)
60        .filter(|&(&v, _)| v != 0.0)
61        .count();
62    writeln!(w, "{} {} {}", matrix.rows(), matrix.cols(), nnz)?;
63
64    for (&v, (i, j)) in matrix {
65        if i < j || v == 0.0 {
66            continue;
67        }
68        writeln!(w, "{} {} {:.16e}", i + 1, j + 1, v)?;
69    }
70    Ok(w)
71}
72
73fn general_mtx_bytes(matrix: &CsMat<f64>) -> Result<Vec<u8>> {
74    let mut w = Vec::new();
75    writeln!(w, "%%MatrixMarket matrix coordinate real general")?;
76    writeln!(w, "% written by powerio")?;
77    writeln!(w, "{} {} {}", matrix.rows(), matrix.cols(), matrix.nnz())?;
78    for (&v, (i, j)) in matrix {
79        writeln!(w, "{} {} {:.16e}", i + 1, j + 1, v)?;
80    }
81    Ok(w)
82}
83
84/// Read a Matrix Market file into a CSR matrix.
85pub fn read_mtx(path: impl AsRef<Path>) -> Result<CsMat<f64>> {
86    let tri: sprs::TriMat<f64> =
87        sprs::io::read_matrix_market(path).map_err(|e| Error::Mtx(e.to_string()))?;
88    Ok(tri.to_csr())
89}
90
91/// Read a dense vector emitted by [`emit_vector_mtx`] (`array real general`):
92/// `%`-comment lines, a `<len> 1` dimensions line, then one value per line.
93pub fn read_vector_mtx(path: impl AsRef<Path>) -> Result<Vec<f64>> {
94    let text = std::fs::read_to_string(path)?;
95    let mut lines = text.lines().filter(|l| !l.starts_with('%'));
96    let header = lines
97        .next()
98        .ok_or_else(|| Error::Mtx("empty vector file".into()))?;
99    let len: usize = header
100        .split_whitespace()
101        .next()
102        .and_then(|t| t.parse().ok())
103        .ok_or_else(|| Error::Mtx(format!("bad vector dimensions line: {header:?}")))?;
104    let values = lines
105        .take(len)
106        .map(|l| {
107            l.trim()
108                .parse::<f64>()
109                .map_err(|_| Error::Mtx(format!("bad vector entry: {l:?}")))
110        })
111        .collect::<Result<Vec<_>>>()?;
112    if values.len() != len {
113        return Err(Error::Mtx(format!(
114            "expected {len} entries, got {}",
115            values.len()
116        )));
117    }
118    Ok(values)
119}
120
121/// Emit a dense vector as Matrix Market `array real general`.
122pub fn emit_vector_mtx(values: &[f64], path: impl AsRef<Path>) -> Result<()> {
123    commit_one_file(path.as_ref(), to_vector_mtx_bytes(values)?)
124}
125
126/// The complete Matrix Market `array real general` text for one vector.
127pub fn to_vector_mtx_bytes(values: &[f64]) -> Result<Vec<u8>> {
128    let mut w = Vec::new();
129    writeln!(w, "%%MatrixMarket matrix array real general")?;
130    writeln!(w, "% written by powerio")?;
131    writeln!(w, "{} 1", values.len())?;
132    for v in values {
133        writeln!(w, "{v:.16e}")?;
134    }
135    Ok(w)
136}
137
138/// Whether the `symmetric` header would round trip: every stored entry has a
139/// stored mirror holding the identical bits.
140///
141/// The writer emits only the lower triangle under that header, so deciding this
142/// on a tolerance sent a merely close matrix out as symmetric and read it back
143/// changed by up to the tolerance. Anything short of exact goes out `general`.
144fn is_exactly_symmetric(a: &CsMat<f64>) -> bool {
145    if a.rows() != a.cols() {
146        return false;
147    }
148    for (i, row) in a.outer_iterator().enumerate() {
149        for (j, &v) in row.iter() {
150            // Bit equality, so a mirrored pair differing only in the sign of
151            // zero is `general` too: the symmetric form would not carry it.
152            match a.get(j, i) {
153                Some(&mirror) if mirror.to_bits() == v.to_bits() => {}
154                _ => return false,
155            }
156        }
157    }
158    true
159}
160
161#[cfg(test)]
162mod tests {
163    use sprs::TriMat;
164
165    use super::emit_mtx;
166
167    #[test]
168    fn single_file_writers_take_any_platform_legal_target_name() {
169        // The portability rule governs inventory names, never which
170        // operating system path a caller may choose: a name that is legal on
171        // the running platform commits.
172        let base = std::env::temp_dir().join(format!(
173            "powerio-mtx-target-names-{}-{}",
174            std::process::id(),
175            std::time::SystemTime::now()
176                .duration_since(std::time::UNIX_EPOCH)
177                .unwrap()
178                .as_nanos()
179        ));
180        std::fs::create_dir_all(&base).unwrap();
181        #[cfg(unix)]
182        let nonportable = ["aux.mtx", "trailing.", "with space "];
183        #[cfg(not(unix))]
184        let nonportable = ["with space.mtx"];
185        for name in nonportable {
186            let target = base.join(name);
187            super::emit_vector_mtx(&[3.0], &target).unwrap_or_else(|error| {
188                panic!("{name}: {error}");
189            });
190            assert_eq!(super::read_vector_mtx(&target).unwrap(), vec![3.0]);
191            // An existing entry at the same platform-legal name still refuses.
192            let error = super::emit_vector_mtx(&[4.0], &target).unwrap_err();
193            assert!(matches!(error, crate::Error::Commit(_)), "{error:?}");
194            assert_eq!(super::read_vector_mtx(&target).unwrap(), vec![3.0]);
195        }
196        // A file name that is not valid UTF-8 is a legal path on Linux
197        // filesystems; APFS refuses the byte sequence itself, so the case is
198        // platform-legal only there.
199        #[cfg(target_os = "linux")]
200        {
201            use std::os::unix::ffi::OsStrExt;
202            let raw =
203                std::ffi::OsStr::from_bytes(&[b'r', b'a', b'w', 0xFF, b'.', b'm', b't', b'x']);
204            let target = base.join(raw);
205            super::emit_vector_mtx(&[5.0], &target).unwrap();
206            assert_eq!(super::read_vector_mtx(&target).unwrap(), vec![5.0]);
207        }
208        let _ = std::fs::remove_dir_all(&base);
209    }
210
211    #[test]
212    fn single_file_writers_never_replace_an_existing_entry() {
213        let path = temp_path("no-clobber-single");
214        std::fs::write(&path, b"precious").unwrap();
215        let error = super::emit_vector_mtx(&[1.0, 2.0], &path).unwrap_err();
216        assert!(matches!(error, crate::Error::Commit(_)), "{error:?}");
217        assert_eq!(std::fs::read(&path).unwrap(), b"precious");
218        let _ = std::fs::remove_file(&path);
219
220        // A fresh target commits and reads back.
221        let fresh = temp_path("no-clobber-single-fresh");
222        super::emit_vector_mtx(&[1.0, 2.0], &fresh).unwrap();
223        assert_eq!(super::read_vector_mtx(&fresh).unwrap(), vec![1.0, 2.0]);
224        let _ = std::fs::remove_file(&fresh);
225    }
226
227    #[test]
228    fn value_asymmetric_matrix_writes_general_mtx() {
229        let mut tri = TriMat::new((2, 2));
230        tri.add_triplet(0, 0, 2.0);
231        tri.add_triplet(0, 1, -1.0);
232        tri.add_triplet(1, 0, -2.0);
233        tri.add_triplet(1, 1, 2.0);
234        let matrix = tri.to_csr();
235
236        let path = temp_path("value-asymmetric");
237        emit_mtx(&matrix, &path).unwrap();
238        let text = std::fs::read_to_string(&path).unwrap();
239        let _ = std::fs::remove_file(&path);
240
241        assert!(
242            text.lines().next().unwrap().ends_with("general"),
243            "value-asymmetric matrices must not be written with a symmetric header"
244        );
245    }
246
247    #[test]
248    fn a_matrix_asymmetric_below_the_old_tolerance_writes_general() {
249        // #292. The pair differs by 1e-15 relative, which the old 1e-12
250        // tolerance called symmetric, so a reader mirrored 3.0 back over the
251        // 3.000000000000001 that was assembled. A `Bp` in BX mode with a small
252        // phase shifter is asymmetric by exactly this little.
253        let mut tri = TriMat::new((2, 2));
254        tri.add_triplet(0, 0, 5.0);
255        tri.add_triplet(0, 1, 3.000_000_000_000_001);
256        tri.add_triplet(1, 0, 3.0);
257        tri.add_triplet(1, 1, 5.0);
258        let matrix = tri.to_csr();
259
260        let path = temp_path("near-symmetric");
261        emit_mtx(&matrix, &path).unwrap();
262        let text = std::fs::read_to_string(&path).unwrap();
263        let _ = std::fs::remove_file(&path);
264
265        assert!(
266            text.lines().next().unwrap().ends_with("general"),
267            "a matrix that is only nearly symmetric must carry both triangles:\n{text}"
268        );
269    }
270
271    #[test]
272    fn a_structurally_asymmetric_matrix_writes_general() {
273        // The mirror is absent rather than unequal: the old check read it as a
274        // stored 0.0 and compared equal whenever the entry was itself 0.0.
275        let mut tri = TriMat::new((2, 2));
276        tri.add_triplet(0, 0, 5.0);
277        tri.add_triplet(0, 1, 0.0);
278        tri.add_triplet(1, 1, 5.0);
279        let matrix = tri.to_csr();
280
281        let path = temp_path("structurally-asymmetric");
282        emit_mtx(&matrix, &path).unwrap();
283        let text = std::fs::read_to_string(&path).unwrap();
284        let _ = std::fs::remove_file(&path);
285
286        assert!(
287            text.lines().next().unwrap().ends_with("general"),
288            "an unmirrored stored entry must not claim a symmetric header:\n{text}"
289        );
290    }
291
292    #[test]
293    fn an_exactly_symmetric_matrix_still_writes_symmetric() {
294        let mut tri = TriMat::new((2, 2));
295        tri.add_triplet(0, 0, 5.0);
296        tri.add_triplet(0, 1, -3.0);
297        tri.add_triplet(1, 0, -3.0);
298        tri.add_triplet(1, 1, 5.0);
299        let matrix = tri.to_csr();
300
301        let path = temp_path("exactly-symmetric");
302        emit_mtx(&matrix, &path).unwrap();
303        let text = std::fs::read_to_string(&path).unwrap();
304        let _ = std::fs::remove_file(&path);
305
306        assert!(
307            text.lines().next().unwrap().ends_with("symmetric"),
308            "an exactly symmetric matrix keeps the compact form:\n{text}"
309        );
310    }
311
312    fn temp_path(stem: &str) -> std::path::PathBuf {
313        let mut path = std::env::temp_dir();
314        let nanos = std::time::SystemTime::now()
315            .duration_since(std::time::UNIX_EPOCH)
316            .map_or(0, |d| d.as_nanos());
317        path.push(format!("powerio-{stem}-{nanos}.mtx"));
318        path
319    }
320}