powerio 0.10.0

Compiler infrastructure for power systems: parse, convert, validate, and lower grid models
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

//! Producer, origin, source descriptors, and source maps.
//!
//! These records identify the producing tool, source artifacts, and the source
//! record mapped to each model field.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

/// The tool and build that produced the package.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct Producer {
    pub tool: String,
    pub version: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_commit: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub features: Vec<String>,
}

impl Producer {
    /// The producer for packages built by this crate version of PowerIO.
    pub fn powerio() -> Self {
        Self {
            tool: "powerio".to_owned(),
            version: env!("CARGO_PKG_VERSION").to_owned(),
            git_commit: None,
            features: Vec::new(),
        }
    }
}

/// Where the package came from. Internally tagged on `kind` in JSON, so a reader
/// distinguishes an in-memory model, a single text file (with or without
/// retained source), a folder dataset, a partially decoded binary, a derived
/// product of a lowering pass, or a composite of several sources.
///
/// The `hash` field is named consistently across all `Origin` variants.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(tag = "kind", rename_all = "snake_case")]
#[non_exhaustive]
pub enum Origin {
    /// Built in process, no source artifact.
    InMemory,
    File {
        path: String,
        format: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        hash: Option<String>,
        /// Whether the original source text was retained for a byte-exact
        /// same-format echo. The retained text itself is not embedded in the
        /// package; this only records that it exists at the frontend.
        #[serde(default)]
        retained_source: bool,
    },
    Folder {
        path: String,
        format: String,
        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
        file_hashes: BTreeMap<String, String>,
    },
    BinaryFile {
        path: String,
        format: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        hash: Option<String>,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        decoded_sections: Vec<String>,
    },
    /// A model produced by a lowering/normalization pass from another package.
    Derived {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        parent_package_id: Option<String>,
        pass: String,
        #[serde(default, skip_serializing_if = "serde_json::Map::is_empty")]
        options: serde_json::Map<String, serde_json::Value>,
    },
    /// Several sources combined, e.g. a static case plus a profile set.
    Composite { sources: Vec<String> },
}

/// A declared source artifact, referenced from source maps and diagnostics by
/// its `id`. (`sources[]` in the package.)
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SourceDescriptor {
    pub id: String,
    pub kind: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub format: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hash: Option<String>,
}

/// A pointer into one source artifact: where a canonical field came from. It
/// lives in `powerio-diag` because a diagnostic carries one.
pub use crate::stored::legacy09::legacy_diag::SourceRef;

/// How a canonical field relates to its source value.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum MappingKind {
    /// Copied verbatim from the source.
    Exact,
    /// Materialized from a format default rather than the source text.
    Defaulted,
    /// Inferred from other source data.
    Inferred,
    /// Converted into canonical units (e.g. ohms to per unit).
    ConvertedUnits,
    /// Produced by a lowering pass (e.g. positive-sequence equivalent).
    Lowered,
    /// One canonical field aggregated from several source records.
    Aggregated,
    /// One source record split into several canonical fields/elements.
    Split,
    /// Synthesized with no direct source (e.g. a generated bus id).
    Synthetic,
    /// Extra data from the source preserved verbatim.
    RetainedExtra,
}

/// How confident the source map entry is.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
pub enum Confidence {
    Exact,
    High,
    Medium,
    Low,
}

/// One `element_path -> source` mapping.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SourceMapEntry {
    /// JSON pointer (or best-effort locator) into the package payload.
    pub element_path: String,
    pub source_ref: SourceRef,
    pub mapping_kind: MappingKind,
    pub confidence: Confidence,
}