.. _auto_ml_predict_ersatz:

*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
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - 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.
   * - Material Name Column
     - name_col
     - text
     - 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
     - text
     - 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
     - text
     - 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
     - text
     - 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
     - text
     - 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
     - text
     - 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
     - text
     - failure_stress
     - 
     - Column name for engineering failure stress; defaults to 'failure_stress'. Predicted by m3 if absent; used by m4 and curve reconstruction.
   * - Pre-Necking Energy Column (PRENE)
     - energy_yu_col
     - text
     - energy_yield_to_ultimate
     - 
     - 
   * - Post-Necking Energy Column (PSTNE)
     - energy_uf_col
     - text
     - energy_ultimate_to_failure
     - 
     - 

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - 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

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>ml_predict_ersatz</code>. Schema hash: <code>ccff419b5b78</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>