Skip to main content

powerio_matrix/io/
sensitivity.rs

1//! Streamed Matrix Market output for DC sensitivity matrices.
2
3use std::fs::File;
4use std::io::{BufReader, BufWriter, Write};
5use std::path::{Path, PathBuf};
6use std::time::{SystemTime, UNIX_EPOCH};
7
8use crate::Result;
9use crate::indexed::IndexedNetwork;
10use crate::matrix::sensitivity::for_each_ptdf_lodf_entry;
11use crate::matrix::{SensitivityMetadata, SensitivityOptions};
12
13/// Emit PTDF and LODF Matrix Market files from the option based sensitivity
14/// path and return the metadata for the same entries. The sparse solver path
15/// streams retained coordinates through temp files, so it does not keep the
16/// full sparse output in memory.
17pub fn emit_sensitivity_mtx_with_options(
18    case: &IndexedNetwork,
19    options: &SensitivityOptions,
20    ptdf_path: impl AsRef<Path>,
21    lodf_path: impl AsRef<Path>,
22) -> Result<SensitivityMetadata> {
23    let mut ptdf = CoordinateMtxWriter::new(ptdf_path.as_ref())?;
24    let mut lodf = CoordinateMtxWriter::new(lodf_path.as_ref())?;
25
26    let metadata = match for_each_ptdf_lodf_entry(
27        case,
28        options,
29        |row, col, value| ptdf.write_entry(row, col, value),
30        |row, col, value| lodf.write_entry(row, col, value),
31    ) {
32        Ok(metadata) => metadata,
33        Err(err) => {
34            ptdf.cleanup();
35            lodf.cleanup();
36            return Err(err);
37        }
38    };
39
40    let ptdf_target = ptdf.target_path.clone();
41    if let Err(error) = ptdf.finish(metadata.ptdf.rows, metadata.ptdf.cols) {
42        // The refused first target must not strand the second writer's
43        // staging files.
44        lodf.cleanup();
45        return Err(error);
46    }
47    if let Err(error) = lodf.finish(metadata.lodf.rows, metadata.lodf.cols) {
48        // The two targets are produced together or neither is: remove the
49        // file this call itself committed at the first target. The commit
50        // refused any pre-existing entry, so this removal can only take back
51        // this call's own output.
52        let _ = std::fs::remove_file(&ptdf_target);
53        return Err(error);
54    }
55    Ok(metadata)
56}
57
58struct CoordinateMtxWriter {
59    target_path: PathBuf,
60    body_path: PathBuf,
61    final_tmp_path: PathBuf,
62    body: Option<BufWriter<File>>,
63    nnz: usize,
64}
65
66impl CoordinateMtxWriter {
67    fn new(target_path: &Path) -> Result<Self> {
68        let (body_path, body) = create_exclusive_staging(target_path, "body")?;
69        // The final staging path is claimed at finish time with the same
70        // exclusive open; here only the name is drawn.
71        let final_tmp_path = temp_path(target_path, "final");
72        Ok(Self {
73            target_path: target_path.to_path_buf(),
74            body_path,
75            final_tmp_path,
76            body: Some(BufWriter::new(body)),
77            nnz: 0,
78        })
79    }
80
81    fn write_entry(&mut self, row: usize, col: usize, value: f64) -> Result<()> {
82        if value == 0.0 {
83            return Ok(());
84        }
85        let body = self
86            .body
87            .as_mut()
88            .expect("coordinate writer body is open before finish");
89        writeln!(body, "{} {} {:.16e}", row + 1, col + 1, value)?;
90        self.nnz += 1;
91        Ok(())
92    }
93
94    fn finish(mut self, rows: usize, cols: usize) -> Result<()> {
95        let result = self.finish_inner(rows, cols);
96        if result.is_err() {
97            // A refused or failed commit leaves no staging file beside the
98            // target; the commit itself already removed the staged output.
99            self.cleanup();
100        }
101        result
102    }
103
104    fn finish_inner(&mut self, rows: usize, cols: usize) -> Result<()> {
105        if let Some(mut body) = self.body.take() {
106            body.flush()?;
107        }
108
109        let (final_tmp_path, staged) = create_exclusive_staging(&self.target_path, "final")?;
110        self.final_tmp_path = final_tmp_path;
111        let mut out = BufWriter::new(staged);
112        writeln!(out, "%%MatrixMarket matrix coordinate real general")?;
113        writeln!(out, "% written by powerio")?;
114        writeln!(out, "{rows} {cols} {}", self.nnz)?;
115        let mut body = BufReader::new(File::open(&self.body_path)?);
116        std::io::copy(&mut body, &mut out)?;
117        out.flush()?;
118        drop(out);
119
120        // The complete staged matrix moves onto the target through the
121        // no-replace commit: an entry at the target refuses the write and the
122        // staged file is removed, leaving the caller's filesystem as it was.
123        powerio_core::__implementation::__commit_staged_file(
124            &self.final_tmp_path,
125            &self.target_path,
126        )?;
127        let _ = std::fs::remove_file(&self.body_path);
128        Ok(())
129    }
130
131    fn cleanup(&mut self) {
132        if let Some(mut body) = self.body.take() {
133            let _ = body.flush();
134        }
135        let _ = std::fs::remove_file(&self.body_path);
136        let _ = std::fs::remove_file(&self.final_tmp_path);
137    }
138}
139
140/// Create one staging file exclusively: an entry already at the drawn name,
141/// of any kind, refuses that name instead of being opened, followed, or
142/// truncated, and a fresh name is drawn for a bounded number of attempts —
143/// the discipline the destination staging applies.
144fn create_exclusive_staging(target_path: &Path, suffix: &str) -> Result<(PathBuf, File)> {
145    for _ in 0..32 {
146        let candidate = temp_path(target_path, suffix);
147        match open_exclusive(&candidate) {
148            Ok(file) => return Ok((candidate, file)),
149            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
150            Err(error) => return Err(error.into()),
151        }
152    }
153    Err(crate::Error::Mtx(format!(
154        "could not choose an unused staging path beside `{}`",
155        target_path.display()
156    )))
157}
158
159/// One exclusive create: an entry of any kind already at `path` — a file, a
160/// directory, a live or dangling symbolic link — is `AlreadyExists`, never
161/// opened, followed, or truncated.
162fn open_exclusive(path: &Path) -> std::io::Result<File> {
163    std::fs::OpenOptions::new()
164        .write(true)
165        .create_new(true)
166        .open(path)
167}
168
169fn temp_path(target_path: &Path, suffix: &str) -> PathBuf {
170    let pid = std::process::id();
171    let nanos = SystemTime::now()
172        .duration_since(UNIX_EPOCH)
173        .map_or(0, |duration| duration.as_nanos());
174    let name = target_path
175        .file_name()
176        .map_or_else(|| "matrix".into(), |name| name.to_string_lossy());
177    target_path.with_file_name(format!(".{name}.{pid}.{nanos}.{suffix}.tmp"))
178}
179
180#[cfg(test)]
181mod staging_tests {
182    use super::*;
183
184    fn scratch(label: &str) -> PathBuf {
185        let dir = std::env::temp_dir().join(format!(
186            "powerio-sensitivity-staging-{label}-{}-{}",
187            std::process::id(),
188            std::time::SystemTime::now()
189                .duration_since(std::time::UNIX_EPOCH)
190                .unwrap()
191                .as_nanos()
192        ));
193        std::fs::create_dir_all(&dir).unwrap();
194        dir
195    }
196
197    #[test]
198    fn the_exclusive_open_refuses_every_kind_of_existing_entry() {
199        let dir = scratch("open-exclusive");
200
201        let file = dir.join("file");
202        std::fs::write(&file, b"kept").unwrap();
203        assert_eq!(
204            open_exclusive(&file).unwrap_err().kind(),
205            std::io::ErrorKind::AlreadyExists
206        );
207        assert_eq!(std::fs::read(&file).unwrap(), b"kept");
208
209        let directory = dir.join("dir");
210        std::fs::create_dir(&directory).unwrap();
211        assert!(open_exclusive(&directory).is_err());
212
213        #[cfg(unix)]
214        {
215            let designated = dir.join("designated");
216            std::fs::write(&designated, b"designated").unwrap();
217            let live = dir.join("live-link");
218            std::os::unix::fs::symlink(&designated, &live).unwrap();
219            assert_eq!(
220                open_exclusive(&live).unwrap_err().kind(),
221                std::io::ErrorKind::AlreadyExists
222            );
223            assert_eq!(std::fs::read(&designated).unwrap(), b"designated");
224
225            let dangling = dir.join("dangling-link");
226            std::os::unix::fs::symlink(dir.join("missing"), &dangling).unwrap();
227            assert!(open_exclusive(&dangling).is_err());
228        }
229
230        // A fresh name opens.
231        assert!(open_exclusive(&dir.join("fresh")).is_ok());
232        let _ = std::fs::remove_dir_all(&dir);
233    }
234}