ML PREDICT ERSATZ — CHAIN M1..M4 + RECONSTRUCT CURVES¶
Chains four surrogate models (m1–m4) trained by ml_learn_ersatz to predict a full set of ERSATZ material anchor points from an input dataset containing at minimum yield strain and yield stress. Each prediction stage feeds the next (YSS→USS→PRENE→FSS→PSTNE), and optionally reconstructs energy-matched engineering stress-strain curves via curves_ersatz_eng.
When to use¶
Tagged: batch, chain-predict, curve-reconstruction, ersatz, lucy_ml, mat_24, materials, predict.
Inputs¶
| Label | ID | Type | Default | Required | Description |
|---|---|---|---|---|---|
| Dataset (starting ersatz values) | dataset | dataset | — | ✓ | Tabular dataset (one row per material) containing at minimum yield_strain and yield_stress columns; any extra columns are passed through unchanged into the predicted_dataset output. |
| Models (keyvalue from ml_learn_ersatz) | models | keyvalue | — | Keyvalue output from ml_learn_ersatz containing entries m1–m4 with their .pkl file paths; multi-target models may carry comma-joined paths. Either this or saved_mathmodels must be wired — if both are present, saved_mathmodels takes precedence. | |
| Saved Math Models (keyvalue from ml_learn_ersatz) | saved_mathmodels | keyvalue | — | Alternative keyvalue to Models for reusing surrogates saved via ml_learn_ersatz’s Math Model Library option; entries m1–m4 each hold an integer mathmodel id that is resolved to its .pkl attachment at predict time. Takes precedence over Models when both are wired. | |
| Reconstruct Curves | reconstruct | select | yes | Whether to also emit reconstructed engineering stress-strain curves via curves_ersatz_eng; set to ‘yes’ (default) to output a CurveGroup, or ‘no’ to return the predicted dataset only. | |
| Predict Anchor Deltas (must match the value used to train the models) | predict_deltas | select | yes | When ‘yes’ (default), the m1 / m3 models predict anchor-to-anchor deltas and this worker reconstructs the absolute eng_ultimate_strain / ultimate_stress / failure_strain / failure_stress columns with max(0, delta) so the predicted strain monotonicity is guaranteed. Must match the predict_deltas flag used to train the models in ml_learn_ersatz; passing the wrong value yields ‘feature missing’ errors because the trained .pkl looks for differently-named columns. | |
| Model Mode (must match the value used to train the models) | model_mode | select | staged | Must match the model_mode used to train the models in ml_learn_ersatz. ‘staged’ looks for m1/m2/m3/m4 entries in the models keyvalue; ‘unified’ looks for a single m_all entry. Mismatch is detected and surfaced as a clear error with a hint to re-train or flip the flag. | |
| Material Name Column | name_col | select | name | Name of the column in the input dataset used to label each material row; defaults to ‘name’ and is used as the curve name during reconstruction. | |
| Eng Yield Strain Column | yld_strain_col | select | yield_strain | Column name carrying engineering yield strain values (dimensionless); defaults to ‘yield_strain’. Must be present in every input row as it is the primary m1 feature. | |
| Eng Yield Stress Column | yld_stress_col | select | yield_stress | Column name carrying engineering yield stress values (force/area, consistent units); defaults to ‘yield_stress’. Must be present in every input row as the second primary m1 feature. | |
| Eng Ultimate Strain Column | ult_strain_col | select | eng_ultimate_strain | Column name for engineering ultimate strain (dimensionless); defaults to ‘eng_ultimate_strain’. May be absent from the input — m1 will predict it and write it under this name for downstream stages. | |
| Eng Ultimate Stress Column | ult_stress_col | select | ultimate_stress | Column name for engineering ultimate stress; defaults to ‘ultimate_stress’. May be absent from the input — m1 predicts it and stages m2–m4 use it as a feature. | |
| Eng Failure Strain Column | fail_strain_col | select | failure_strain | Column name for engineering failure strain (dimensionless); defaults to ‘failure_strain’. Predicted by m3 if absent; used by m4 and curve reconstruction. | |
| Eng Failure Stress Column | fail_stress_col | select | failure_stress | Column name for engineering failure stress; defaults to ‘failure_stress’. Predicted by m3 if absent; used by m4 and curve reconstruction. | |
| Post-Necking Shape Column | post_shape_col | select | post_shape | Column name for the post-necking shape parameter (default: ‘post_shape’). When the surrogate predicted this column at train time, set this so the reconstructed engineering stress-strain curve picks up the per-material post-necking softening shape instead of falling back to curve_ersatz_eng’s built-in default. | |
| Post-Necking Power Column | post_power_col | select | post_power | Column name for the post-necking power parameter (default: ‘post_power’); pairs with post_shape_col when the shape model is power-law. | |
| Damage at Failure Column | damage_max_col | select | damage_max | Column name for the damage-at-failure scalar (default: ‘damage_max’). | |
| Plateau Fraction Column | plateau_frac_col | select | plateau_fraction | Column name for the plateau fraction (default: ‘plateau_fraction’); characterises the flat region of the stress-strain curve. | |
| Pre-Ultimate Shape Column | pre_ult_shape_col | select | pre_ult_shape | Column name for the pre-ultimate shape exponent (default: ‘pre_ult_shape’). | |
| Pre-Ultimate Power Column | pre_ult_power_col | select | pre_ult_power | Column name for the pre-ultimate power exponent (default: ‘pre_ult_power’). | |
| Voce K Column | voce_k_col | select | voce_k | Column name for the Voce saturation parameter K (default: ‘voce_k’); used when the curve was fitted with a Voce-type hardening law. | |
| Pre-Necking Energy Column (PRENE) | energy_yu_col | select | energy_yield_to_ultimate | ||
| Post-Necking Energy Column (PSTNE) | energy_uf_col | select | energy_ultimate_to_failure | ||
| Ultimate Strain Plateau Column (optional) | ult_strain_plateau_col | select | ultimate_strain_plateau | Column name for the absolute plateau-end strain (default: ‘ultimate_strain_plateau’). Only consumed when the upstream ml_learn_ersatz emitted an ‘m_plat’ entry — i.e. the training stats_dataset carried this column. When present, m_plat is run after the m1..m4 / m_all chain and the predicted value is appended to each row; the curve reconstruction step then derives plateau_fraction from it (overriding any plateau_frac_col mapping for that row), so the rebuilt engineering stress-strain curve respects the per-material plateau width. Silently skipped when m_plat is missing from the keyvalue, so legacy workflows trained without plateau are unaffected. | |
| Elastic Modulus Column | elastic_modulus_col | select | modulus | Column name carrying the per-row elastic modulus (default: ‘modulus’ — the engstress_stats key). When the input dataset is built from engstress_stats this column is already populated; for prediction-time rows that only have yield, set default_elastic_modulus below and the worker injects the fallback per row. Used by curves_ersatz_eng to build a true linear-elastic + flat-yield-plateau region when E is consistent with the offset-yield anchor; falls back silently to the legacy single-line elastic when E is 0 or inconsistent. | |
| Default Elastic Modulus (used when row lacks the column) | default_elastic_modulus | number | 0.0 | Per-row fallback for the elastic modulus, in the same units as the rest of the curve (e.g. MPa). Injected into rows that don’t already carry the configured Elastic Modulus Column. Typical values: 210000 for steel, 70000 for aluminum, 2000-4000 for engineering polymers. Default 0 (off) preserves the legacy single-line elastic behavior so existing workflows are unchanged. Rows that already carry the modulus column are NEVER overwritten. | |
| Pre-Ult Mid Stress Column | pre_ult_mid_stress_col | select | eng_mid_yu_stress | Column carrying the engineering stress at the strain midpoint between yield and ultimate (default ‘eng_mid_yu_stress’ — the engstress_stats key). When present on a row, ersatz_eng back-fits the pre-ult shape parameter so the reconstructed curve passes through this midpoint (overrides the energy-based fit, which is integral and less directly informative). Optional — leave the column missing on prediction-time rows that have only yield + anchors and the energy fit fires as before. | |
| Pre-Ult Mid Strain Column | pre_ult_mid_strain_col | select | eng_mid_yu_strain | Per-row column carrying the strain at the yield-to-ultimate midpoint (default ‘eng_mid_yu_strain’). Pairs with Pre-Ult Mid Stress Column. When the strain lies between yield and ultimate, the reconstruction uses it as the actual midpoint anchor — fits shapes whose inflection isn’t at t=0.5. | |
| Post-Ult Mid Stress Column | post_ult_mid_stress_col | select | eng_mid_uf_stress | Column carrying the engineering stress at the strain midpoint between ultimate and failure (default ‘eng_mid_uf_stress’ — the engstress_stats key). When present on a row, ersatz_eng back-fits the post-ult shape parameter (for power_concave_*) or the q exponent (for damage_based) so the reconstructed curve passes through this midpoint. Particularly helpful for plateau-then-cliff curves where σ_mid ≈ σ_ult — energy alone leaves the shape under-constrained. | |
| Post-Ult Mid Strain Column | post_ult_mid_strain_col | select | eng_mid_uf_strain | Per-row column carrying the strain at the ultimate-to-failure midpoint (default ‘eng_mid_uf_strain’). Pairs with Post-Ult Mid Stress Column. | |
| Smooth Ultimate Peak (apply C1 bridge at the ultimate point) | smooth_ultimate | select | no | Replaces a small band on either side of ε_ult with a cubic-Hermite spline that pins slope=0 at the peak, so reconstructed engineering stress-strain curves don’t show a corner where pre- meets post-ultimate. ‘auto’ engages only when the underlying shape combination would actually leave a visible corner. | |
| Smooth Ultimate Bridge Width Fraction | smooth_ultimate_width_frac | number | 0.05 | Half-width of the smoothing band as a fraction of min(Δε_pre, Δε_post). Smaller → tighter, more local fix; larger → broader, smoother peak. Range [0, 0.5]. Ignored when smooth_ultimate=no. | |
| Pre-Ultimate Hardening Shape | pre_ult_shape | select | power | Curve family for the yield→ultimate segment. ‘power’ (default) = σ_yld + Δσ·t^p_hard (legacy sqrt-style rise). ‘voce’ = saturating exponential. ‘peak’ = concave-up family that hits zero slope at ε_ult by construction (pairs naturally with post_shape=’power_concave_down’ for a smooth peak without needing the bridge). | |
| Pre-Ultimate Peak Power (used when pre_ult_shape=’peak’) | pre_ult_peak_power | number | 2.0 | Exponent p_peak in σ(t) = σ_yld + Δσ·(1-(1-t)^p_peak). p_peak ≥ 1; larger → curve sits closer to σ_ult through more of the segment before tapering in. Auto-tuned when energy_yield_to_ultimate is provided. Ignored for non-‘peak’ shapes. | |
| Post-Ultimate Softening Shape | post_shape | select | damage_based | Curve family for the ultimate→failure segment. ‘damage_based’ (default) = (1 - D_max·t^q) softening. ‘linear’ = straight drop. ‘power_concave_down’ / ‘power_concave_up’ = power-law families. Picked up per-row only when the input dataset (or m_shape_post) didn’t already supply post_shape — row values win. | |
| Material Metadata | metadata | dataset | — | Optional per-material metadata, joined onto the prediction dataset by the name column. The metadata columns used as features and which stages consume them are read from the trained models’ manifest — they are not re-specified here. |
Outputs¶
| Label | ID | Type | Description |
|---|---|---|---|
| Predicted Ersatz Values | predicted_dataset | dataset | Input dataset enriched with all four predicted anchor columns (ultimate strain/stress, PRENE energy, failure strain/stress, PSTNE energy); one row per input material, all original columns preserved. |
| Reconstructed Curves (curves_ersatz_eng) | reconstructed_curves | vector | CurveGroup of energy-matched engineering stress-strain curves (pre-neck and post-neck segments) built by curves_ersatz_eng from the predicted anchors; null when Reconstruct Curves is set to ‘no’ or reconstruction fails. The same per-material curve is also attached to each row of predicted_dataset under the column predicted_eng_stress_strain (added when Reconstruct Curves is yes), so downstream dataset workers can carry the predicted curve next to its anchors. |
Disciplines¶
- ai_ml.surrogate
- data.curve.transform
- engineering.material.calibration
- engineering.material.characterization
- engineering.material.specimen
Auto-generated from platform schema. Worker id: ml_predict_ersatz. Schema hash: 8dce46b2f0f0. Hand-curated docs in workerexamples/ override this page when present.