solidcraft-upstream/docs/physical-material-cards.md

Physical material data cards

material.properties.validate {card} checks a caller-supplied candidate record, without assigning it, saving it in the design, reading files, fetching sources or changing history, selection, camera or live geometry. This is phase 1 of #923/#922, building towards #785. Existing material.create/edit and their density/appearance behavior are unchanged. The design format is unchanged.

Validation means numerical and structural consistency. It does not authenticate sources, approve redistribution, certify design values, provide a solver or enable advanced rendering. The result reports analysis_solver_available: false and rendering_properties_available: false. Missing properties remain unknown.

Contract (standalone card schema 1)

Candidate review window

Search for Validate Physical Material Data in the command palette (or use ui.start with material.properties.validate) to open the candidate reviewer. Paste a schema-1 card object and choose Review card. The existing engine validator checks it; the window shows known properties in SI units, unknown properties, per-property conditions and source claims as inert text. Material-local axes do not assign a frame to a body. Isotropic G/K come from the engine report.

Editing the input clears the previous review. Invalid input shows its refusal without retaining a stale valid result. Input is capped at 262,144 characters and 256 KiB before JSON parsing; the validator's tighter structural and text budgets still apply. The window does not read files, fetch references, assign properties, replace density, modify history or save the candidate. Close discards it. Calling the engine's JSON command still returns its report without opening a dialog.

This main-based review unit is independent of assigned-card persistence, local file import and the design-owned inspector follow-up in #1094. No dataset or rendering capability is supplied by reviewing a candidate.

A card has schema_version: 1, designation, family (wood, polymer, glass, metal, other), sources and properties. Source IDs are exact, case-sensitive local references. Each source has id, title, kind (user_supplied, measurement, public_reference, illustrative), optional license and reference strings. These strings are metadata supplied by the caller; even a declared open license remains in source_review_required. Nothing is downloaded.

Every property has data, source_id and optional conditions. Conditions are temperature_k, moisture_dry_basis_kg_kg, strain_rate_per_s and a free-text state (grade, temper, processing or specimen condition). Conditions belong to the property, not an assumed global room temperature. An elastic block represents constants measured under the same conditions and source; mixed-condition curves and independently sourced constants need a later representation.

data.kind	Explicit SI fields
density	kg_m3
elasticity	model, described below
tensile_strength, compressive_strength, yield_strength, shear_strength	pa
thermal_conductivity	w_m_k: [k1,k2,k3], axes
thermal_expansion	per_k: [a1,a2,a3], axes
specific_heat	j_kg_k

Directional values use axes: material123 (material-local 1/2/3) or wood_lrt (longitudinal/radial/tangential). These labels do not assign a frame to a body or infer mechanical orientation from texture rotation. Equal directional values can describe an isotropic thermal property. Thermal expansion may be zero or negative.

An isotropic elastic model has symmetry: isotropic, young_modulus_pa and poisson_ratio. Stability requires E > 0 and -1 < nu < 0.5. Valid auxetic values are accepted. The result derives G = E/[2(1+nu)] and K = E/[3(1-2nu)], in Pa.

An orthotropic model has symmetry: orthotropic, axes, young_moduli_pa: [E1,E2,E3], shear_moduli_pa: [G12,G23,G31] and poisson_ratios: [nu12,nu23,nu31]. Here nu_ij = -eps_j/eps_i under stress along i; reciprocity supplies nu_ij/Ei = nu_ji/Ej. The normal compliance is symmetric with diagonal 1/Ei and off-diagonal -nu_ij/Ei. Diagonal scaling produces unit diagonal; Sylvester's criterion checks its positive definiteness. All three shear moduli must be positive. General orthotropic Poisson ratios are not capped at 0.5. Moduli whose reciprocals cannot be represented finitely are rejected; the isotropic derived response and its reciprocals must also remain finite/positive.

Moisture is kg water / kg dry material and can exceed one. It is not a wet-mass fraction. Unspecified temperature/state, wood moisture or polymer strain rate are reported in unspecified_conditions; they are not guessed or replaced by zero. The validation report also returns missing_condition_fields, a map from each incomplete property kind to its exact absent field names. Temperature and state apply to every family; wood additionally checks dry-basis moisture and polymers strain rate, following the same reporting policy as unspecified_conditions. For example, a wood density with temperature and state but no moisture reports {"density":["moisture_dry_basis_kg_kg"]}. Complete properties are omitted; an empty card returns an empty map, without inventing properties or conditions. This detail is read-only and does not change admission or the saved card schema. Older serialized validation reports without the map deserialize with an empty map; regenerate validation from the card to obtain the missing-field detail. The family label does not certify that a chosen constitutive model fits a material. Scalar strengths are individual measurements, not a three-dimensional failure envelope. Typed strength directions and test methods remain a separate extension.

Admission limits

Before cloning/deserializing JSON: at most 2,048 nodes, depth 12, 32 array entries or object fields and a 256 KiB conservative accounting budget (32 bytes per node plus string/key bytes). The typed record allows 32 sources and 16 properties; duplicate source IDs or property kinds and unknown fields are rejected.

Text limits in UTF-8 bytes: designation/title 256, source ID 128, license 512, reference 2,048 and state 1,024; controls and blank text are rejected. All numeric values must be finite. Positive-value upper admission limits are density 1e6 kg/m³, moduli/strengths 1e15 Pa, conductivity 1e9 W/(m K), heat capacity 1e9 J/(kg K), temperature 20,000 K and strain rate 1e12 /s. Expansion is within ±1 /K, dry-basis moisture within [0,1e6] (also accommodating highly hydrated polymers), orthotropic Poisson ratios within ±1e6 in addition to the compliance stability test. These are generous technical admission limits, not measured applicability ranges or a conditioning guarantee for a future solver.

Original synthetic example

These deliberately invented constants demonstrate validation, not a real grade:

{
  "card": {
    "schema_version": 1,
    "designation": "Synthetic elastic example — not design data",
    "family": "other",
    "sources": [{
      "id": "example",
      "title": "Original synthetic example",
      "kind": "illustrative",
      "license": "MIT OR Apache-2.0"
    }],
    "properties": [{
      "data": {
        "kind": "elasticity",
        "model": {"symmetry": "isotropic", "young_modulus_pa": 12000000000, "poisson_ratio": 0.25}
      },
      "source_id": "example"
    }]
  }
}

The result has G = 4.8e9 Pa, K = 8e9 Pa, unspecified conditions and source review still required. No assigned mass, saved material or appearance changes.

Next phases and references

Persistence/library integration needs a separately reviewed document migration, atomic edits, undo/redo and offline reopening, coordinated with #863. Curves, uncertainty, hardness scales, viscoelasticity and failure criteria remain later work. Visual PBR/texture/environment consumption uses the renderer contract requested in #813, with #909/#837 input utilities; accepting physical data advertises none of those capabilities.

The USDA Wood Handbook, including chapter 4's dry-mass moisture definition, is a public scientific reference for moisture, mechanical behavior and the distinction between specimen properties and graded design values. No handbook data/table is bundled. The Khronos PBR material model is a reference for the separate optical track. No third-party code, engineering dataset or asset is added by this implementation.

Directional elasticity query

material.properties.directional {card, direction: [x,y,z]} reports Young's modulus in Pa for a uniaxial, small-strain constitutive test along a material-local direction. It returns the safely normalized direction, declared axes (null for isotropy), and the full validation/source/condition report. It neither assigns axes to a body nor predicts a part's displacement, failure, strength or safety factor. No solver or render capability is enabled. Missing elasticity refuses instead of inventing data.

For orthotropy, let n=(x,y,z) be the unit direction. With engineering shear compliance 1/G and the reciprocal Poisson convention above:

1/E(n) = x^4/E1 + y^4/E2 + z^4/E3
       + x²y²(1/G12 - 2 nu12/E1)
       + y²z²(1/G23 - 2 nu23/E2)
       + z²x²(1/G31 - 2 nu31/E3).

This follows by applying stress sigma = n tensor n, computing strain with the symmetric compliance, then contracting n with strain and n. The implementation uses a Cholesky sum of squares for the normal contribution, avoiding cancellation between the positive diagonal and negative coupling terms. Shear contributions are also nonnegative. Isotropy returns E directly, independent of orientation.

Input directions must contain exactly three finite numbers and be nonzero; arbitrary magnitude is allowed. Max-component scaling avoids overflow or underflow while normalizing very large or tiny vectors. Unrepresentable compliance/modulus refuses; this finite-precision check does not establish a condition-number certificate. The card's test conditions still apply; changing direction does not extrapolate temperature, moisture, process, rate, damage or nonlinear behavior. Synthetic analytic tests cover principal axes, the isotropic limit and off-axis shear/coupling terms. No physical dataset or external implementation is included.