Merge pull request #613 from EnergySystemsModellingLab/output-metadata

Write metadata to TOML file in output folder

Author: alexdewar

Cargo.lock

@@ -30,7 +30,11 @@ highs = "1.8.0"
 indexmap = "2.9.0"
 human-panic = "2.0.2"
 clap-markdown = "0.1.5"
+platform-info = "2.0.5"
 
 [dev-dependencies]
 regex = "1.11.1"
 rstest = {version = "0.25.0", default-features = false, features = ["crate-name"]}
+
+[build-dependencies]
+built = {version = "0.8.0", features = ["chrono", "git2"]}

Cargo.toml

@@ -0,0 +1,4 @@
+/// Write data about build
+fn main() {
+    built::write_built_file().expect("Failed to acquire build-time information");
+}

build.rs

@@ -196,7 +196,12 @@ pub fn load_model<P: AsRef<Path>>(model_dir: P) -> Result<(Model, AssetPool)> {
     let agent_ids = agents.keys().cloned().collect();
     let assets = read_assets(model_dir.as_ref(), &agent_ids, &processes, &region_ids)?;
 
+    let model_path = model_dir
+        .as_ref()
+        .canonicalize()
+        .context("Could not parse path to model")?;
     let model = Model {
+        model_path,
         milestone_years: model_file.milestone_years.years,
         agents,
         commodities,

src/input.rs

@@ -7,12 +7,14 @@ use crate::region::{RegionID, RegionMap};
 use crate::time_slice::TimeSliceInfo;
 use anyhow::{ensure, Context, Result};
 use serde::Deserialize;
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 const MODEL_FILE_NAME: &str = "model.toml";
 
 /// Model definition
 pub struct Model {
+    /// Path to model folder
+    pub model_path: PathBuf,
     /// Milestone years for the simulation. Sorted.
     pub milestone_years: Vec<u32>,
     /// Agents for the simulation

src/model.rs

@@ -14,6 +14,9 @@ use std::fs;
 use std::fs::File;
 use std::path::{Path, PathBuf};
 
+pub mod metadata;
+use metadata::write_metadata;
+
 /// The root folder in which model-specific output folders will be created
 const OUTPUT_DIRECTORY_ROOT: &str = "muse2_results";
 
@@ -233,8 +236,11 @@ impl DataWriter {
     /// # Arguments
     ///
     /// * `output_path` - Folder where files will be saved
+    /// * `model_path` - Path to input model
     /// * `save_debug_info` - Whether to include extra CSV files for debugging model
-    pub fn create(output_path: &Path, save_debug_info: bool) -> Result<Self> {
+    pub fn create(output_path: &Path, model_path: &Path, save_debug_info: bool) -> Result<Self> {
+        write_metadata(output_path, model_path).context("Failed to save metadata")?;
+
         let new_writer = |file_name| {
             let file_path = output_path.join(file_name);
             csv::Writer::from_path(file_path)
@@ -340,7 +346,7 @@ mod tests {
 
         // Write an asset
         {
-            let mut writer = DataWriter::create(dir.path(), false).unwrap();
+            let mut writer = DataWriter::create(dir.path(), dir.path(), false).unwrap();
             writer.write_assets(milestone_year, assets.iter()).unwrap();
             writer.flush().unwrap();
         }
@@ -367,7 +373,7 @@ mod tests {
         // Write a flow
         let dir = tempdir().unwrap();
         {
-            let mut writer = DataWriter::create(dir.path(), false).unwrap();
+            let mut writer = DataWriter::create(dir.path(), dir.path(), false).unwrap();
             writer.write_flows(milestone_year, &flow_map).unwrap();
             writer.flush().unwrap();
         }
@@ -398,7 +404,7 @@ mod tests {
 
         // Write a price
         {
-            let mut writer = DataWriter::create(dir.path(), false).unwrap();
+            let mut writer = DataWriter::create(dir.path(), dir.path(), false).unwrap();
             writer.write_prices(milestone_year, &prices).unwrap();
             writer.flush().unwrap();
         }

src/output.rs

@@ -0,0 +1,128 @@
+//! Code for writing metadata to file
+use anyhow::Result;
+use chrono::prelude::*;
+use platform_info::{PlatformInfo, PlatformInfoAPI, UNameAPI};
+use serde::Serialize;
+use std::fs;
+use std::path::Path;
+
+/// The output file name for metadata
+const METADATA_FILE_NAME: &str = "metadata.toml";
+
+/// Information about the program build via `built` crate
+mod built_info {
+    // The file has been placed there by the build script.
+    include!(concat!(env!("OUT_DIR"), "/built.rs"));
+}
+
+/// Get information about program version from git
+fn get_git_hash() -> String {
+    let Some(hash) = built_info::GIT_COMMIT_HASH_SHORT else {
+        return "unknown".into();
+    };
+
+    if built_info::GIT_DIRTY == Some(true) {
+        format!("{hash}-dirty")
+    } else {
+        hash.into()
+    }
+}
+
+/// Metadata about the program run, build and version information for MUSE and the user's system
+#[derive(Serialize)]
+struct Metadata<'a> {
+    run: RunMetadata<'a>,
+    program: ProgramMetadata<'a>,
+    platform: PlatformMetadata,
+}
+
+/// Information about the model run
+#[derive(Serialize)]
+struct RunMetadata<'a> {
+    /// Path to the model which was run
+    model_path: &'a Path,
+    /// The date and time on which the run started
+    datetime: String,
+}
+
+impl<'a> RunMetadata<'a> {
+    fn new(model_path: &'a Path) -> Self {
+        let dt = Local::now();
+        Self {
+            model_path,
+            datetime: dt.to_rfc2822(),
+        }
+    }
+}
+
+#[derive(Serialize)]
+struct ProgramMetadata<'a> {
+    /// The program name
+    name: &'a str,
+    /// The program version as specified in Cargo.toml
+    version: &'a str,
+    /// The target architecture for the build (e.g. x86_64-unknown-linux-gnu)
+    target: &'a str,
+    /// Whether it is a debug build
+    is_debug: bool,
+    /// The version of rustc used to compile MUSE
+    rustc_version: &'a str,
+    /// When MUSE was built
+    build_time_utc: &'a str,
+    /// The git commit hash for the version of MUSE (if known)
+    git_commit_hash: String,
+}
+
+impl Default for ProgramMetadata<'_> {
+    fn default() -> Self {
+        Self {
+            name: built_info::PKG_NAME,
+            version: built_info::PKG_VERSION,
+            target: built_info::TARGET,
+            is_debug: built_info::DEBUG,
+            rustc_version: built_info::RUSTC_VERSION,
+            build_time_utc: built_info::BUILT_TIME_UTC,
+            git_commit_hash: get_git_hash(),
+        }
+    }
+}
+
+/// Information about the platform on which MUSE is running.
+///
+/// The fields correspond to different data available from the [`PlatformInfo`] struct.
+#[derive(Serialize)]
+struct PlatformMetadata {
+    sysname: String,
+    nodename: String,
+    release: String,
+    version: String,
+    machine: String,
+    osname: String,
+}
+
+impl Default for PlatformMetadata {
+    fn default() -> Self {
+        let info = PlatformInfo::new().expect("Unable to determine platform info");
+        Self {
+            sysname: info.sysname().to_string_lossy().into(),
+            nodename: info.nodename().to_string_lossy().into(),
+            release: info.release().to_string_lossy().into(),
+            version: info.version().to_string_lossy().into(),
+            machine: info.machine().to_string_lossy().into(),
+            osname: info.osname().to_string_lossy().into(),
+        }
+    }
+}
+
+/// Write metadata to the specified output path in TOML format
+pub fn write_metadata(output_path: &Path, model_path: &Path) -> Result<()> {
+    let metadata = Metadata {
+        run: RunMetadata::new(model_path),
+        program: ProgramMetadata::default(),
+        platform: PlatformMetadata::default(),
+    };
+    let file_path = output_path.join(METADATA_FILE_NAME);
+    fs::write(&file_path, toml::to_string(&metadata)?)?;
+
+    Ok(())
+}

src/output/metadata.rs

@@ -27,7 +27,7 @@ pub fn run(
     output_path: &Path,
     debug_model: bool,
 ) -> Result<()> {
-    let mut writer = DataWriter::create(output_path, debug_model)?;
+    let mut writer = DataWriter::create(output_path, &model.model_path, debug_model)?;
 
     // Iterate over milestone years
     let mut year_iter = model.iter_years();