gugen 0.3.0

Explainable materials synthesis and process planning
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

//! gugen (具現): explainable materials synthesis and process planning.
//!
//! This crate turns a target inorganic composition (and optionally a target
//! structure) into candidate precursor sets, balanced reactions, and
//! solid-state process plans — each with its evidence, assumptions, and
//! unresolved conditions kept explicit. It does not predict experimental
//! success. See `docs/scientific_scope.md` for what is and is not in
//! scope, and `CHANGELOG.md` for the user-facing capability list.
//!
//! This implements typed errors, validated numeric types, composition,
//! target specification, the public report schema, provenance, provider
//! trait boundaries, exact
//! reaction balancing, bounded precursor-set search, a solid-state process
//! template, plan scoring/confidence, end-to-end orchestration via
//! `Planner`, an optional `mikiwame` structural-diagnostics adapter, a
//! CLI (`src/bin/gugen.rs`: `plan`, `balance`, `explain`, `validate-target`,
//! `doctor`, `batch`), a validation suite against curated literature
//! fixtures (`tests/`, `docs/benchmark_report.md`), and v0.1 release
//! preparation (license files, docs.rs metadata, a dependency license
//! audit — see `tasks/todo.md`'s Phase 9 section). The `chematic-crystal`
//! adapter remained blocked on that crate's publication through v0.1
//! (Phase 16 below addresses part of this), and two
//! validation findings are documented rather than fixed (see
//! `tasks/todo.md`'s Phase 8 section). **v0.1.0 is published** (crates.io,
//! merged to `main`, tagged `v0.1.0`) — see `tasks/todo.md`'s Phase 9
//! section for the release record. Post-v0.1 development toward v0.2.0
//! (Phase 10-14 — real literature-sourced process conditions, a
//! large-scale blind benchmark, a second route family, a thermodynamic-
//! provider adapter boundary, and a validation-fixture citation repair) is
//! tracked from `tasks/todo.md`'s Phase 10 section onward, not `AGENTS.md`
//! §26 (which only defines the original 9 phases). **v0.2.0 is published**
//! (crates.io, tagged `v0.2.0`). Work toward v0.3.0 has begun with Phase
//! 15A (`route_suitability` module): a report-level evidence model for
//! whether a route family suits a target (`Supports`/`Contradicts`/
//! `Unknown` findings, never an aggregated score). Phase 15B added
//! `derive_recommendation`, a pure function deriving a discrete
//! `RouteRecommendation` from that evidence, and wired only its
//! `NotRecommended` state into `Planner::plan`: a plan with strong,
//! uncontested contradicting evidence is moved from `plans` into the new
//! `SynthesisPlanningReport.not_recommended` (kept, with its findings, not
//! dropped), and a target where every generated plan is excluded this way
//! abstains explicitly via `unresolved` rather than returning an empty
//! success. No numeric score is affected by either phase. Phase 16 added
//! an optional `chematic_crystal` feature: `to_mikiwame_structure`
//! converts a caller-supplied `chematic_crystal::PeriodicStructure` (now
//! published, 0.15.0) into a `mikiwame::OwnedStructure`, closing the
//! specific conversion gap the mikiwame adapter had named since Phase 6.
//! Still not auto-wired into `Planner::plan` -- `TargetSpecification` has
//! no geometry field, so a caller still applies the result themselves.
//! Phase 17 audited how much literature evidence for route suitability
//! actually exists in a real synthesis corpus, and evaluated
//! `derive_recommendation` against a hand-verified holdout record --
//! explicitly not a route-family prediction-accuracy benchmark (see
//! `docs/route_suitability_corpus_audit.md`); no production code changed.
//! Phases 15A/15B/16/17 together are v0.3.0's planned development work.
//! See `CHANGELOG.md` for the user-facing summary.

#![forbid(unsafe_code)]

mod balance;
#[cfg(feature = "chematic_crystal")]
mod chematic_crystal_adapter;
mod composition;
mod config;
mod error;
mod evidence;
mod frac;
mod literature_conditions;
#[cfg(feature = "materials_project")]
mod materials_project_adapter;
#[cfg(feature = "mikiwame")]
mod mikiwame_adapter;
mod planner;
mod precursor;
mod process;
mod provenance;
mod provider;
mod reaction;
mod rejection;
mod report;
mod route_suitability;
mod score;
mod target;

pub use balance::{balance, curated_byproducts};
#[cfg(feature = "chematic_crystal")]
pub use chematic_crystal_adapter::to_mikiwame_structure;
pub use composition::{Composition, ELEMENT_SYMBOLS, Element};
pub use config::{PlanningConfig, SearchBudget};
pub use error::{GugenError, ProviderError, Result};
pub use evidence::{EvidenceKind, EvidenceScope, EvidenceStrength, PlanningEvidence};
pub use literature_conditions::{CuratedConditionRecord, InMemoryLiteratureConditionProvider};
#[cfg(feature = "materials_project")]
pub use materials_project_adapter::MaterialsProjectSnapshotProvider;
#[cfg(feature = "mikiwame")]
pub use mikiwame_adapter::{StructuralDiagnosticEffects, structural_effects};
pub use planner::Planner;
pub use precursor::{
    AcceptedPrecursorSet, AvailabilityMetadata, InMemoryPrecursorCatalog, PrecursorCandidate,
    PrecursorId, PrecursorSearchOutcome, PrecursorSelection, search_precursor_sets,
};
pub use process::{
    Atmosphere, CharacterizationMethod, ConditionPrecedent, CoolingMode, DurationRange,
    FormingMethod, GrindingMethod, HeatingPurpose, InertGas, MaterialAmount, MixingMethod,
    PlannedStep, PressureRange, ProcessPrecedent, ProcessStep, ProcessTemplateResult,
    RampRateRange, ReducingAgent, RouteFamily, StepRequirement, TemperatureRange,
    applicable_route_family_templates, conventional_solid_state_template, mechanochemical_template,
};
pub use provenance::PlanningProvenance;
pub use provider::{
    PrecursorCatalog, ProcessEvidenceProvider, RouteSuitabilityProvider, ThermodynamicProvider,
};
pub use reaction::{
    BalancedReaction, CompetingPhase, ReactionEnergy, ReactionSpecies, ThermodynamicConditions,
};
pub use rejection::{RejectedCandidate, RejectionCode};
pub use report::{
    ApplicabilityAssessment, ApplicabilityLevel, NotRecommendedPlan, PlanId, PlanningWarning,
    SCHEMA_VERSION, SynthesisPlan, SynthesisPlanningReport, TargetSummary, UnresolvedRequirement,
    WarningSeverity,
};
pub use route_suitability::{
    CuratedSuitabilityRecord, InMemoryRouteSuitabilityProvider, RouteRecommendation,
    RouteSuitabilityAssessment, SuitabilityFinding, SuitabilityVerdict, derive_recommendation,
};
pub use score::{
    ConfidenceAssessment, PlanAssessment, PlanScoreBreakdown, PlanningAssumption, RankingWeights,
    Score01, ranking_weights_digest, score_plan,
};
pub use target::{
    PhaseRequirement, PlanningConstraints, TargetMaterialView, TargetSpecification, TargetStructure,
};