use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use nalgebra::DMatrix;
use physics_in_parallel::prelude::basic::{
Backend, IndexedRng, Matrix, MatrixError, ResolvedRng, RngError, RngMethod,
};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use thiserror::Error;
use crate::artifact::{
ArtifactDescriptor, ArtifactDisposition, ArtifactError, ArtifactLoadError,
load_verified_artifact, persist_artifact,
};
pub const INTERACTION_ARTIFACT_REFERENCE_FORMAT: &str =
"ecological.interaction-artifact-reference.v2";
pub const INTERACTION_MATRIX_FORMAT: &str = "ecological.interaction-matrix.v2";
pub const INTERACTION_MATRIX_METADATA_KEY: &str = "interaction_matrix";
pub const INTERACTION_GENERATOR_IDENTITY: &str = "ecological_state_toolkit.interaction_matrix";
pub const INTERACTION_GENERATOR_VERSION: &str = "4";
const DOMAIN_INDEPENDENT: u64 = 0x73d8_ba6e_209f_54c1;
const DOMAIN_CONNECTANCE: u64 = 0x5c1a_9f20_f678_314d;
const DOMAIN_FIRST_NORMAL: u64 = 0x9841_d60a_334b_c8e7;
const DOMAIN_SECOND_NORMAL: u64 = 0xa72e_1b49_963c_05fd;
#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum MatrixNormalization {
None,
SqrtSpecies,
}
impl MatrixNormalization {
fn divisor(self, species: usize) -> f64 {
match self {
Self::None => 1.0,
Self::SqrtSpecies => (species as f64).sqrt(),
}
}
}
#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
pub enum DiagonalPolicy {
Zero,
Constant(f64),
Sampled,
}
impl DiagonalPolicy {
fn fixed_value(self) -> Option<f64> {
match self {
Self::Zero => Some(0.0),
Self::Constant(value) => Some(value),
Self::Sampled => None,
}
}
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum SignStructure {
Competition,
Mutualism,
ConsumerResource,
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(tag = "family", rename_all = "snake_case", deny_unknown_fields)]
pub enum InteractionMatrixRecipe {
RandomUniform {
minimum: f64,
maximum: f64,
#[serde(default = "default_indexed_rng")]
rng: ResolvedRng,
},
RandomGaussian {
mean: f64,
standard_deviation: f64,
#[serde(default = "default_indexed_rng")]
rng: ResolvedRng,
},
CorrelatedGaussian {
mean: f64,
standard_deviation: f64,
reciprocal_correlation: f64,
#[serde(default = "one")]
connectance: f64,
#[serde(default = "zero_diagonal")]
diagonal: DiagonalPolicy,
#[serde(default = "sqrt_species")]
normalization: MatrixNormalization,
#[serde(default = "default_indexed_rng")]
rng: ResolvedRng,
},
SignStructuredGaussian {
structure: SignStructure,
scale: f64,
#[serde(default = "one")]
connectance: f64,
#[serde(default = "zero_diagonal")]
diagonal: DiagonalPolicy,
#[serde(default = "sqrt_species")]
normalization: MatrixNormalization,
#[serde(default = "default_indexed_rng")]
rng: ResolvedRng,
},
}
const fn sqrt_species() -> MatrixNormalization {
MatrixNormalization::SqrtSpecies
}
const fn zero_diagonal() -> DiagonalPolicy {
DiagonalPolicy::Zero
}
const fn one() -> f64 {
1.0
}
impl InteractionMatrixRecipe {
pub fn validate(&self, species: usize) -> Result<(), InteractionRecipeError> {
if species == 0 {
return Err(InteractionRecipeError::EmptySpecies);
}
match self {
Self::RandomUniform {
minimum, maximum, ..
} => {
require_finite("minimum", *minimum)?;
require_finite("maximum", *maximum)?;
if minimum >= maximum {
return Err(InteractionRecipeError::InvalidRange {
minimum: *minimum,
maximum: *maximum,
});
}
}
Self::RandomGaussian {
mean,
standard_deviation,
..
} => {
require_finite("mean", *mean)?;
require_nonnegative_finite("standard_deviation", *standard_deviation)?;
}
Self::CorrelatedGaussian {
mean,
standard_deviation,
connectance,
diagonal,
..
} => {
require_finite("mean", *mean)?;
require_nonnegative_finite("standard_deviation", *standard_deviation)?;
require_probability(*connectance)?;
if let Some(value) = diagonal.fixed_value() {
require_finite("diagonal", value)?;
}
}
Self::SignStructuredGaussian {
scale,
connectance,
diagonal,
..
} => {
require_nonnegative_finite("scale", *scale)?;
require_probability(*connectance)?;
let value = diagonal.fixed_value().ok_or(
InteractionRecipeError::SampledDiagonalUnsupported {
family: "sign_structured_gaussian",
},
)?;
require_finite("diagonal", value)?;
}
}
if let Self::CorrelatedGaussian {
reciprocal_correlation,
..
} = self
&& (!reciprocal_correlation.is_finite()
|| !(-1.0..=1.0).contains(reciprocal_correlation))
{
return Err(InteractionRecipeError::InvalidParameter {
name: "reciprocal_correlation",
value: *reciprocal_correlation,
});
}
Ok(())
}
pub fn generate(&self, species: usize) -> Result<InteractionMatrix, InteractionRecipeError> {
self.validate(species)?;
let key = IndexedRng::new(self.rng())?;
let resolved_recipe = self.with_rng(key.resolved_rng());
let matrix_len = species
.checked_mul(species)
.ok_or(InteractionRecipeError::MatrixSizeOverflow { species })?;
let mut values = vec![0.0; matrix_len];
match &resolved_recipe {
Self::RandomUniform {
minimum, maximum, ..
} => {
fill_indexed_uniform(
&mut values,
species,
key,
DOMAIN_INDEPENDENT ^ species as u64,
*minimum,
*maximum,
);
}
Self::RandomGaussian {
mean,
standard_deviation,
..
} => {
fill_indexed_normal(
&mut values,
species,
key,
DOMAIN_INDEPENDENT ^ species as u64,
*mean,
*standard_deviation,
);
}
Self::CorrelatedGaussian {
mean,
standard_deviation,
reciprocal_correlation,
connectance,
diagonal,
normalization,
..
} => {
let samples = sample_structured_inputs(key, species, matrix_len);
let first_normal = samples.first_normal;
let second_normal = samples.second_normal;
let connection_uniform = samples.connection_uniform;
let divisor = normalization.divisor(species);
for index in 0..species {
values[index * species + index] = diagonal.fixed_value().unwrap_or_else(|| {
(mean + standard_deviation * first_normal[index * species + index])
/ divisor
});
}
let independent_weight = (1.0 - reciprocal_correlation.powi(2)).sqrt();
for row in 0..species {
for column in (row + 1)..species {
let index = row * species + column;
if *connectance < 1.0 && connection_uniform[index] >= *connectance {
continue;
}
let first = first_normal[index];
let second = second_normal[index];
values[row * species + column] =
(mean + standard_deviation * first) / divisor;
values[column * species + row] = (mean
+ standard_deviation
* (reciprocal_correlation * first + independent_weight * second))
/ divisor;
}
}
}
Self::SignStructuredGaussian {
structure,
scale,
connectance,
diagonal,
normalization,
..
} => {
let samples = sample_structured_inputs(key, species, matrix_len);
let first_normal = samples.first_normal;
let second_normal = samples.second_normal;
let connection_uniform = samples.connection_uniform;
fill_diagonal(
&mut values,
species,
diagonal
.fixed_value()
.expect("sampled diagonal rejected during validation"),
);
let magnitude = scale / normalization.divisor(species);
for row in 0..species {
for column in (row + 1)..species {
let index = row * species + column;
if *connectance < 1.0 && connection_uniform[index] >= *connectance {
continue;
}
let first = first_normal[index].abs() * magnitude;
let second = second_normal[index].abs() * magnitude;
let (forward, reverse) = match structure {
SignStructure::Competition => (-first, -second),
SignStructure::Mutualism => (first, second),
SignStructure::ConsumerResource => (first, -second),
};
values[row * species + column] = forward;
values[column * species + row] = reverse;
}
}
}
}
let generator = GeneratorProvenance::new(
INTERACTION_GENERATOR_IDENTITY,
INTERACTION_GENERATOR_VERSION,
serde_json::to_value(&resolved_recipe)?,
Some(key.resolved_rng()),
)?;
Ok(InteractionMatrix::from_generated(
Matrix::from_values(species, species, Backend::Dense, values)?,
generator,
)?)
}
pub const fn rng(&self) -> ResolvedRng {
match self {
Self::RandomUniform { rng, .. }
| Self::RandomGaussian { rng, .. }
| Self::CorrelatedGaussian { rng, .. }
| Self::SignStructuredGaussian { rng, .. } => *rng,
}
}
fn with_rng(&self, resolved: ResolvedRng) -> Self {
let mut recipe = self.clone();
match &mut recipe {
Self::RandomUniform { rng, .. }
| Self::RandomGaussian { rng, .. }
| Self::CorrelatedGaussian { rng, .. }
| Self::SignStructuredGaussian { rng, .. } => *rng = resolved,
}
recipe
}
}
struct StructuredSamples {
first_normal: Vec<f64>,
second_normal: Vec<f64>,
connection_uniform: Vec<f64>,
}
fn sample_structured_inputs(
key: IndexedRng,
species: usize,
matrix_len: usize,
) -> StructuredSamples {
let mut first_normal = vec![0.0; matrix_len];
let mut second_normal = vec![0.0; matrix_len];
let mut connection_uniform = vec![0.0; matrix_len];
fill_indexed_normal(
&mut first_normal,
species,
key,
DOMAIN_FIRST_NORMAL ^ species as u64,
0.0,
1.0,
);
fill_indexed_normal(
&mut second_normal,
species,
key,
DOMAIN_SECOND_NORMAL ^ species as u64,
0.0,
1.0,
);
fill_indexed_uniform(
&mut connection_uniform,
species,
key,
DOMAIN_CONNECTANCE ^ species as u64,
0.0,
1.0,
);
StructuredSamples {
first_normal,
second_normal,
connection_uniform,
}
}
fn fill_indexed_uniform(
values: &mut [f64],
components: usize,
key: IndexedRng,
domain: u64,
minimum: f64,
maximum: f64,
) {
let width = maximum - minimum;
for (index, value) in values.iter_mut().enumerate() {
*value = minimum
+ width
* key.unit_f64(
0,
domain,
(index / components) as u64,
(index % components) as u64,
0,
);
}
}
fn fill_indexed_normal(
values: &mut [f64],
components: usize,
key: IndexedRng,
domain: u64,
mean: f64,
standard_deviation: f64,
) {
for (index, value) in values.iter_mut().enumerate() {
*value = mean
+ standard_deviation
* key.standard_normal(
0,
domain,
(index / components) as u64,
(index % components) as u64,
);
}
}
fn default_indexed_rng() -> ResolvedRng {
ResolvedRng::from_entropy(RngMethod::IndexedSplitMix64)
}
fn fill_diagonal(values: &mut [f64], species: usize, diagonal: f64) {
for index in 0..species {
values[index * species + index] = diagonal;
}
}
fn require_finite(name: &'static str, value: f64) -> Result<(), InteractionRecipeError> {
if value.is_finite() {
Ok(())
} else {
Err(InteractionRecipeError::InvalidParameter { name, value })
}
}
fn require_nonnegative_finite(
name: &'static str,
value: f64,
) -> Result<(), InteractionRecipeError> {
if value.is_finite() && value >= 0.0 {
Ok(())
} else {
Err(InteractionRecipeError::InvalidParameter { name, value })
}
}
fn require_probability(value: f64) -> Result<(), InteractionRecipeError> {
if value.is_finite() && (0.0..=1.0).contains(&value) {
Ok(())
} else {
Err(InteractionRecipeError::InvalidParameter {
name: "connectance",
value,
})
}
}
#[derive(Clone, Debug)]
pub struct InteractionMatrix {
values: Arc<Matrix<f64>>,
provenance: InteractionProvenance,
}
#[derive(Clone, Debug)]
pub struct TruncatedSvdApproximation {
retained_rank: usize,
retained_spectral_energy: f64,
relative_reconstruction_error: f64,
matrix: InteractionMatrix,
}
impl TruncatedSvdApproximation {
pub const fn retained_rank(&self) -> usize {
self.retained_rank
}
pub const fn retained_spectral_energy(&self) -> f64 {
self.retained_spectral_energy
}
pub const fn relative_reconstruction_error(&self) -> f64 {
self.relative_reconstruction_error
}
pub const fn matrix(&self) -> &InteractionMatrix {
&self.matrix
}
pub fn into_matrix(self) -> InteractionMatrix {
self.matrix
}
}
#[derive(Clone, Debug)]
pub struct TruncatedSvdSeries {
singular_values: Vec<f64>,
approximations: Vec<TruncatedSvdApproximation>,
}
#[derive(Clone, Debug)]
pub struct PersistedTruncatedSvdApproximation {
approximation: TruncatedSvdApproximation,
persisted: PersistedInteraction,
}
impl PersistedTruncatedSvdApproximation {
pub const fn approximation(&self) -> &TruncatedSvdApproximation {
&self.approximation
}
pub const fn persisted(&self) -> &PersistedInteraction {
&self.persisted
}
}
#[derive(Clone, Debug)]
pub struct PersistedTruncatedSvdSeries {
singular_values: Vec<f64>,
approximations: Vec<PersistedTruncatedSvdApproximation>,
}
impl PersistedTruncatedSvdSeries {
pub fn singular_values(&self) -> &[f64] {
&self.singular_values
}
pub fn approximations(&self) -> &[PersistedTruncatedSvdApproximation] {
&self.approximations
}
}
impl TruncatedSvdSeries {
pub fn singular_values(&self) -> &[f64] {
&self.singular_values
}
pub fn approximations(&self) -> &[TruncatedSvdApproximation] {
&self.approximations
}
pub fn approximation(&self, retained_rank: usize) -> Option<&TruncatedSvdApproximation> {
self.approximations
.iter()
.find(|approximation| approximation.retained_rank == retained_rank)
}
}
impl InteractionMatrix {
pub fn from_matrix(values: Matrix<f64>) -> Result<Self, InteractionMatrixError> {
Self::resolve(
Arc::new(values),
InteractionProvenance::InMemory { label: None },
)
}
pub fn from_shared(values: Arc<Matrix<f64>>) -> Result<Self, InteractionMatrixError> {
Self::resolve(values, InteractionProvenance::InMemory { label: None })
}
pub fn from_labeled_matrix(
values: Matrix<f64>,
label: impl Into<String>,
) -> Result<Self, InteractionMatrixError> {
let label = label.into();
if label.trim().is_empty() {
return Err(InteractionMatrixError::EmptyLabel);
}
Self::resolve(
Arc::new(values),
InteractionProvenance::InMemory { label: Some(label) },
)
}
pub fn from_rows(rows: Vec<Vec<f64>>) -> Result<Self, InteractionMatrixError> {
let row_count = rows.len();
if row_count == 0 {
return Err(InteractionMatrixError::EmptySpecies);
}
let column_count = rows.first().map_or(0, Vec::len);
for (row, values) in rows.iter().enumerate() {
if values.len() != column_count {
return Err(InteractionMatrixError::RaggedRows {
row,
expected: column_count,
actual: values.len(),
});
}
}
let values = Matrix::from_values(
row_count,
column_count,
Backend::Dense,
rows.into_iter().flatten().collect(),
)?;
Self::resolve(Arc::new(values), InteractionProvenance::Inline)
}
pub fn load_json(path: &Path) -> Result<Self, InteractionMatrixError> {
let path = path.to_path_buf();
let bytes = fs::read(&path).map_err(|source| InteractionMatrixError::Io {
path: path.clone(),
source,
})?;
Self::from_json_bytes(
bytes,
path.clone(),
InteractionProvenance::JsonFile { path },
)
}
pub fn from_generated(
values: Matrix<f64>,
generator: GeneratorProvenance,
) -> Result<Self, InteractionMatrixError> {
Self::resolve(
Arc::new(values),
InteractionProvenance::Generated { generator },
)
}
pub fn species(&self) -> usize {
self.values.rows()
}
pub fn values(&self) -> &Matrix<f64> {
&self.values
}
pub fn shared_values(&self) -> Arc<Matrix<f64>> {
Arc::clone(&self.values)
}
#[inline]
pub fn coefficient(&self, row: usize, column: usize) -> f64 {
self.values
.get(row, column)
.expect("validated interaction coordinate")
}
#[inline]
pub fn mul_vector_into(&self, input: &[f64], output: &mut [f64]) -> Result<(), MatrixError> {
self.values.mul_vector_into(input, output)
}
#[inline]
pub fn mul_vectors_into(&self, input: &[f64], output: &mut [f64]) -> Result<(), MatrixError> {
self.values.mul_vectors_into(input, output)
}
pub const fn provenance(&self) -> &InteractionProvenance {
&self.provenance
}
pub fn antisymmetrize(&self) -> Result<Self, InteractionMatrixError> {
let transposed = self.values.transpose()?;
let values = self.values.subtract(&transposed)?;
self.derive(values, InteractionTransformation::Antisymmetrize)
}
pub fn scale(&self, scalar: f64) -> Result<Self, InteractionMatrixError> {
require_finite_transform("scalar", scalar)?;
self.derive(
self.values.scale(scalar),
InteractionTransformation::Scale { scalar },
)
}
pub fn abs(&self) -> Result<Self, InteractionMatrixError> {
self.derive(self.values.abs(), InteractionTransformation::Abs)
}
pub fn truncated_svd_series(
&self,
retained_ranks: &[usize],
) -> Result<TruncatedSvdSeries, InteractionMatrixError> {
if retained_ranks.is_empty() {
return Err(InteractionMatrixError::EmptyRetainedRanks);
}
let species = self.species();
for (index, &rank) in retained_ranks.iter().enumerate() {
if rank == 0 || rank > species {
return Err(InteractionMatrixError::InvalidRetainedRank { rank, species });
}
if retained_ranks[..index].contains(&rank) {
return Err(InteractionMatrixError::DuplicateRetainedRank { rank });
}
}
let source = self.values.values().collect::<Vec<_>>();
let svd = DMatrix::from_row_slice(species, species, &source).svd(true, true);
let u = svd.u.expect("SVD requested left singular vectors");
let v_t = svd.v_t.expect("SVD requested right singular vectors");
let singular_values = svd.singular_values.as_slice().to_vec();
let requested = retained_ranks
.iter()
.copied()
.collect::<std::collections::BTreeSet<_>>();
let maximum = *requested.last().expect("validated ranks are nonempty");
let mut reconstructed = vec![0.0; species * species];
let mut matrices = std::collections::BTreeMap::new();
for component in 0..maximum {
let singular_value = singular_values[component];
for row in 0..species {
let left = u[(row, component)] * singular_value;
for column in 0..species {
reconstructed[row * species + column] += left * v_t[(component, column)];
}
}
let rank = component + 1;
if requested.contains(&rank) {
matrices.insert(rank, reconstructed.clone());
}
}
let total_energy = singular_values
.iter()
.map(|value| value * value)
.sum::<f64>();
let source_norm = source.iter().map(|value| value * value).sum::<f64>().sqrt();
let approximations = retained_ranks
.iter()
.copied()
.map(|retained_rank| {
let values = matrices
.remove(&retained_rank)
.expect("every validated requested rank was reconstructed");
let retained_energy = singular_values[..retained_rank]
.iter()
.map(|value| value * value)
.sum::<f64>();
let retained_spectral_energy = if total_energy == 0.0 {
1.0
} else {
retained_energy / total_energy
};
let error = source
.iter()
.zip(&values)
.map(|(source, approximation)| (source - approximation).powi(2))
.sum::<f64>()
.sqrt();
let relative_reconstruction_error = if source_norm == 0.0 {
0.0
} else {
error / source_norm
};
let matrix = Matrix::from_values(species, species, Backend::Dense, values)?;
let matrix = self.derive(
matrix,
InteractionTransformation::TruncatedSvd {
retained_rank,
retained_spectral_energy,
relative_reconstruction_error,
},
)?;
Ok(TruncatedSvdApproximation {
retained_rank,
retained_spectral_energy,
relative_reconstruction_error,
matrix,
})
})
.collect::<Result<Vec<_>, InteractionMatrixError>>()?;
Ok(TruncatedSvdSeries {
singular_values,
approximations,
})
}
pub fn clamp_min(&self, minimum: f64) -> Result<Self, InteractionMatrixError> {
require_finite_transform("minimum", minimum)?;
let rows = self.values.rows();
let columns = self.values.columns();
self.derive(
Matrix::from_fn(rows, columns, Backend::Dense, |row, column| {
self.values
.get(row, column)
.expect("validated interaction coordinate")
.max(minimum)
})?,
InteractionTransformation::ClampMin { minimum },
)
}
pub fn clamp_max(&self, maximum: f64) -> Result<Self, InteractionMatrixError> {
require_finite_transform("maximum", maximum)?;
let rows = self.values.rows();
let columns = self.values.columns();
self.derive(
Matrix::from_fn(rows, columns, Backend::Dense, |row, column| {
self.values
.get(row, column)
.expect("validated interaction coordinate")
.min(maximum)
})?,
InteractionTransformation::ClampMax { maximum },
)
}
pub fn ensure_max_abs_at_most(&self, threshold: f64) -> Result<(), InteractionMatrixError> {
if !threshold.is_finite() || threshold < 0.0 {
return Err(InteractionMatrixError::InvalidTransformationParameter {
name: "threshold",
value: threshold,
});
}
let maximum = self.values.max_abs_real();
if maximum > threshold {
return Err(InteractionMatrixError::MaximumAbsoluteEntryExceeded {
threshold,
maximum,
});
}
Ok(())
}
pub fn normalize(&self, threshold: f64) -> Result<Self, InteractionMatrixError> {
if !threshold.is_finite() || threshold < 0.0 {
return Err(InteractionMatrixError::InvalidTransformationParameter {
name: "threshold",
value: threshold,
});
}
let maximum = self.values.max_abs_real();
let scalar = if maximum > threshold {
threshold / maximum
} else {
1.0
};
let transformation = InteractionTransformation::Normalize {
threshold,
maximum,
scalar,
};
if scalar == 1.0 {
return Ok(Self {
values: Arc::clone(&self.values),
provenance: self.derived_provenance(transformation),
});
}
self.derive(self.values.scale(scalar), transformation)
}
pub const fn generator_rng_config(&self) -> Option<ResolvedRng> {
self.provenance.generator_rng_config()
}
fn from_json_bytes(
bytes: Vec<u8>,
path: PathBuf,
provenance: InteractionProvenance,
) -> Result<Self, InteractionMatrixError> {
let values =
serde_json::from_slice(&bytes).map_err(|source| InteractionMatrixError::Json {
path: path.clone(),
source,
})?;
Self::resolve(Arc::new(values), provenance)
}
fn derive(
&self,
values: Matrix<f64>,
transformation: InteractionTransformation,
) -> Result<Self, InteractionMatrixError> {
Self::resolve(Arc::new(values), self.derived_provenance(transformation))
}
fn derived_provenance(
&self,
transformation: InteractionTransformation,
) -> InteractionProvenance {
InteractionProvenance::Derived {
source: Box::new(self.provenance.clone()),
transformation,
}
}
fn resolve(
values: Arc<Matrix<f64>>,
provenance: InteractionProvenance,
) -> Result<Self, InteractionMatrixError> {
let rows = values.rows();
let columns = values.columns();
if rows != columns {
return Err(InteractionMatrixError::NonSquare { rows, columns });
}
for (flat, value) in values.values().enumerate() {
if !value.is_finite() {
return Err(InteractionMatrixError::NonFiniteEntry {
row: flat / columns,
column: flat % columns,
value,
});
}
}
Ok(Self { values, provenance })
}
}
fn require_finite_transform(name: &'static str, value: f64) -> Result<(), InteractionMatrixError> {
if value.is_finite() {
Ok(())
} else {
Err(InteractionMatrixError::InvalidTransformationParameter { name, value })
}
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum InteractionSourceKind {
InMemory,
Inline,
JsonFile,
Generated,
Derived,
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(tag = "operation", rename_all = "snake_case", deny_unknown_fields)]
pub enum InteractionTransformation {
Antisymmetrize,
Abs,
Scale {
scalar: f64,
},
ClampMin {
minimum: f64,
},
ClampMax {
maximum: f64,
},
Normalize {
threshold: f64,
maximum: f64,
scalar: f64,
},
TruncatedSvd {
retained_rank: usize,
retained_spectral_energy: f64,
relative_reconstruction_error: f64,
},
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum InteractionProvenance {
InMemory {
label: Option<String>,
},
Inline,
JsonFile {
path: PathBuf,
},
Generated {
generator: GeneratorProvenance,
},
Derived {
source: Box<InteractionProvenance>,
transformation: InteractionTransformation,
},
}
impl InteractionProvenance {
pub const fn kind(&self) -> InteractionSourceKind {
match self {
Self::InMemory { .. } => InteractionSourceKind::InMemory,
Self::Inline => InteractionSourceKind::Inline,
Self::JsonFile { .. } => InteractionSourceKind::JsonFile,
Self::Generated { .. } => InteractionSourceKind::Generated,
Self::Derived { .. } => InteractionSourceKind::Derived,
}
}
pub const fn generator(&self) -> Option<&GeneratorProvenance> {
match self {
Self::Generated { generator } => Some(generator),
Self::Derived { source, .. } => source.generator(),
_ => None,
}
}
pub const fn generator_rng_config(&self) -> Option<ResolvedRng> {
match self.generator() {
Some(generator) => generator.rng_config(),
None => None,
}
}
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GeneratorProvenance {
identity: String,
version: String,
recipe: Value,
rng: Option<ResolvedRng>,
}
impl GeneratorProvenance {
pub fn new(
identity: impl Into<String>,
version: impl Into<String>,
recipe: Value,
rng: Option<ResolvedRng>,
) -> Result<Self, InteractionMatrixError> {
let identity = identity.into();
let version = version.into();
if identity.trim().is_empty() {
return Err(InteractionMatrixError::InvalidGeneratorLabel { field: "identity" });
}
if version.trim().is_empty() {
return Err(InteractionMatrixError::InvalidGeneratorLabel { field: "version" });
}
Ok(Self {
identity,
version,
recipe,
rng,
})
}
pub fn identity(&self) -> &str {
&self.identity
}
pub fn version(&self) -> &str {
&self.version
}
pub const fn recipe(&self) -> &Value {
&self.recipe
}
pub const fn rng(&self) -> Option<ResolvedRng> {
self.rng
}
pub const fn rng_config(&self) -> Option<ResolvedRng> {
self.rng
}
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct InteractionArtifactDescriptor {
format: String,
species: usize,
#[serde(flatten)]
artifact: ArtifactDescriptor,
provenance: InteractionProvenance,
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct InteractionArtifactReference {
format: String,
artifact_root: PathBuf,
descriptor: InteractionArtifactDescriptor,
}
impl InteractionArtifactReference {
pub fn new(artifact_root: PathBuf, descriptor: InteractionArtifactDescriptor) -> Self {
Self {
format: INTERACTION_ARTIFACT_REFERENCE_FORMAT.to_owned(),
artifact_root,
descriptor,
}
}
pub fn from_json_bytes(bytes: &[u8]) -> Result<Self, InteractionArtifactLoadError> {
let reference: Self =
serde_json::from_slice(bytes).map_err(|source| InteractionMatrixError::Json {
path: PathBuf::from("<interaction-artifact-reference>"),
source,
})?;
reference.validate()?;
Ok(reference)
}
pub fn load_json(path: &Path) -> Result<Self, InteractionArtifactLoadError> {
let path = path.to_path_buf();
let bytes = fs::read(&path).map_err(|source| InteractionMatrixError::Io {
path: path.clone(),
source,
})?;
let reference: Self =
serde_json::from_slice(&bytes).map_err(|source| InteractionMatrixError::Json {
path: path.clone(),
source,
})?;
reference.validate()?;
Ok(reference)
}
pub fn to_json_bytes(&self) -> Result<Vec<u8>, serde_json::Error> {
serde_json::to_vec_pretty(self)
}
pub fn resolve(&self) -> Result<InteractionMatrix, InteractionArtifactLoadError> {
self.validate()?;
load_verified_interaction_matrix(&self.artifact_root, &self.descriptor)
}
pub fn artifact_root(&self) -> &Path {
&self.artifact_root
}
pub const fn descriptor(&self) -> &InteractionArtifactDescriptor {
&self.descriptor
}
pub fn validate(&self) -> Result<(), InteractionArtifactLoadError> {
if self.format != INTERACTION_ARTIFACT_REFERENCE_FORMAT
|| self.artifact_root.as_os_str().is_empty()
{
Err(InteractionArtifactLoadError::InvalidDescriptor)
} else {
Ok(())
}
}
}
impl InteractionArtifactDescriptor {
pub fn format(&self) -> &str {
&self.format
}
pub const fn species(&self) -> usize {
self.species
}
pub const fn shape(&self) -> [usize; 2] {
[self.species, self.species]
}
pub fn sha256(&self) -> &str {
self.artifact.sha256()
}
pub fn path(&self) -> &Path {
self.artifact.path()
}
pub const fn source_kind(&self) -> InteractionSourceKind {
self.provenance.kind()
}
pub const fn generator(&self) -> Option<&GeneratorProvenance> {
self.provenance.generator()
}
pub const fn provenance(&self) -> &InteractionProvenance {
&self.provenance
}
pub fn insert_into_metadata(&self, metadata: &mut Map<String, Value>) -> Option<Value> {
metadata.insert(
INTERACTION_MATRIX_METADATA_KEY.to_owned(),
serde_json::to_value(self).expect("interaction descriptor is JSON-compatible"),
)
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct PersistedInteraction {
descriptor: InteractionArtifactDescriptor,
disposition: ArtifactDisposition,
}
impl PersistedInteraction {
pub const fn descriptor(&self) -> &InteractionArtifactDescriptor {
&self.descriptor
}
pub const fn disposition(&self) -> ArtifactDisposition {
self.disposition
}
pub fn into_descriptor(self) -> InteractionArtifactDescriptor {
self.descriptor
}
}
pub fn persist_interaction_matrix(
artifact_root: &Path,
matrix: &InteractionMatrix,
) -> Result<PersistedInteraction, InteractionArtifactError> {
let bytes = serde_json::to_vec(matrix.values())?;
let persisted = persist_artifact(artifact_root, "interaction", "json", &bytes)?;
Ok(PersistedInteraction {
descriptor: InteractionArtifactDescriptor {
format: INTERACTION_MATRIX_FORMAT.to_owned(),
species: matrix.species(),
artifact: persisted.descriptor().clone(),
provenance: matrix.provenance().clone(),
},
disposition: persisted.disposition(),
})
}
pub fn persist_truncated_svd_series(
artifact_root: &Path,
source: &InteractionMatrix,
retained_ranks: &[usize],
) -> Result<PersistedTruncatedSvdSeries, InteractionSvdArtifactError> {
let TruncatedSvdSeries {
singular_values,
approximations,
} = source.truncated_svd_series(retained_ranks)?;
let approximations = approximations
.into_iter()
.map(|approximation| {
let persisted = persist_interaction_matrix(artifact_root, approximation.matrix())?;
Ok(PersistedTruncatedSvdApproximation {
approximation,
persisted,
})
})
.collect::<Result<Vec<_>, InteractionArtifactError>>()?;
Ok(PersistedTruncatedSvdSeries {
singular_values,
approximations,
})
}
pub fn load_verified_interaction_matrix(
artifact_root: &Path,
descriptor: &InteractionArtifactDescriptor,
) -> Result<InteractionMatrix, InteractionArtifactLoadError> {
if descriptor.format != INTERACTION_MATRIX_FORMAT || descriptor.species == 0 {
return Err(InteractionArtifactLoadError::InvalidDescriptor);
}
let verified = load_verified_artifact(artifact_root, &descriptor.artifact)?;
let path = verified.path().to_path_buf();
let matrix = InteractionMatrix::from_json_bytes(
verified.into_bytes(),
path,
descriptor.provenance.clone(),
)?;
if matrix.species() != descriptor.species {
return Err(InteractionMatrixError::SpeciesMismatch {
expected: descriptor.species,
actual: matrix.species(),
}
.into());
}
Ok(matrix)
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum InteractionRecipeError {
#[error("interaction recipe requires at least one species")]
EmptySpecies,
#[error("interaction recipe parameter {name} is invalid: {value}")]
InvalidParameter { name: &'static str, value: f64 },
#[error("uniform interaction range requires minimum < maximum, got [{minimum}, {maximum})")]
InvalidRange { minimum: f64, maximum: f64 },
#[error("interaction family {family} does not support sampled diagonal entries")]
SampledDiagonalUnsupported { family: &'static str },
#[error("interaction matrix size overflows usize for {species} species")]
MatrixSizeOverflow { species: usize },
#[error(transparent)]
Rng(#[from] RngError),
#[error(transparent)]
Matrix(#[from] MatrixError),
#[error(transparent)]
Interaction(#[from] InteractionMatrixError),
#[error(transparent)]
Json(#[from] serde_json::Error),
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum InteractionMatrixError {
#[error(transparent)]
Matrix(#[from] MatrixError),
#[error("interaction matrix species dimension must be positive")]
EmptySpecies,
#[error("interaction matrix must be square, found {rows}x{columns}")]
NonSquare { rows: usize, columns: usize },
#[error("interaction matrix has {actual} species, expected {expected}")]
SpeciesMismatch { expected: usize, actual: usize },
#[error("interaction matrix row {row} has {actual} columns, expected {expected}")]
RaggedRows {
row: usize,
expected: usize,
actual: usize,
},
#[error("interaction matrix entry ({row}, {column}) is not finite: {value}")]
NonFiniteEntry {
row: usize,
column: usize,
value: f64,
},
#[error("interaction matrix transformation parameter {name} is invalid: {value}")]
InvalidTransformationParameter { name: &'static str, value: f64 },
#[error("retained_ranks must contain at least one rank")]
EmptyRetainedRanks,
#[error("retained SVD rank {rank} must be in 1..={species}")]
InvalidRetainedRank { rank: usize, species: usize },
#[error("retained_ranks repeats rank {rank}")]
DuplicateRetainedRank { rank: usize },
#[error("interaction matrix maximum absolute entry {maximum} exceeds threshold {threshold}")]
MaximumAbsoluteEntryExceeded { threshold: f64, maximum: f64 },
#[error("interaction matrix label must not be empty")]
EmptyLabel,
#[error("failed to read interaction matrix at `{path}`")]
Io {
path: PathBuf,
#[source]
source: std::io::Error,
},
#[error("invalid interaction matrix JSON at `{path}`")]
Json {
path: PathBuf,
#[source]
source: serde_json::Error,
},
#[error("interaction generator {field} must not be empty")]
InvalidGeneratorLabel { field: &'static str },
#[error("interaction generator `{identity}` has unresolved RNG")]
UnresolvedGeneratorRng { identity: String },
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum InteractionArtifactError {
#[error(transparent)]
Serialize(#[from] serde_json::Error),
#[error(transparent)]
Artifact(#[from] ArtifactError),
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum InteractionSvdArtifactError {
#[error(transparent)]
Matrix(#[from] InteractionMatrixError),
#[error(transparent)]
Artifact(#[from] InteractionArtifactError),
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum InteractionArtifactLoadError {
#[error("invalid interaction artifact descriptor")]
InvalidDescriptor,
#[error(transparent)]
Artifact(#[from] ArtifactLoadError),
#[error(transparent)]
Matrix(#[from] InteractionMatrixError),
}