.. _auto_mc_curve_generator:

*MONTE CARLO — GENERATE ROBUSTNESS CURVES*
==========================================

Generates N synthetic curves around one or more input curves for robustness studies and uncertainty propagation. Two sampling methods are available. Pointwise (default) computes empirical pointwise mean and std and draws RBF-smoothed Gaussian noise around them — fast, intuitive, but tends to produce roughly parallel sigma bands. PCA (recommended when 3+ input curves available) decomposes the input family into principal components, samples in PCA score space, and reconstructs; this preserves the spatially-varying scatter pattern (narrow where inputs cluster, wide where they diverge). Optional monotonic guard keeps stress-strain draws non-decreasing.

When to use
-----------

Tagged: ``curve``, ``monte_carlo``, ``robustness``, ``uncertainty``, ``variance``, ``generator``, ``gaussian_process``, ``sampling``.

Inputs
------

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

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Input Curves
     - curves
     - vector
     - —
     - ✓
     - One or more reference curves on a common x-axis. Multiple curves drive an empirical pointwise mean and std; a single curve falls back to sigma_percent.
   * - Number of Curves to Generate
     - n_samples
     - integer
     - 100
     - ✓
     - How many synthetic curves to produce. Typical 50-200 for robustness sweeps.
   * - Sigma Percent (single-curve fallback)
     - sigma_percent
     - scalar
     - 0.1
     - 
     - Relative noise level used only when a single input curve is provided. 0.10 = 10% of /y/ at each x. Ignored when 2+ input curves are connected.
   * - Correlation Length (fraction of x-range) — pointwise mode only
     - correlation_length
     - scalar
     - 0.05
     - 
     - Smoothness knob for pointwise mode, expressed as a fraction of the x-range (0.05 = 5%). Larger values produce smoother, more shape-faithful draws; values near 0 produce jagged per-point noise. Ignored when sampling_method = pca.
   * - Sampling Method
     - sampling_method
     - select
     - pointwise
     - 
     - pointwise = empirical mean/std + RBF noise (fast, default). pca = principal-component decomposition of the input family + sampling in score space (preserves spatially-varying scatter; recommended when 3+ input curves are available). PCA mode falls back to pointwise when fewer than 3 input curves are provided.
   * - PCA Variance Threshold
     - pca_variance_threshold
     - scalar
     - 0.95
     - 
     - PCA mode only. Cumulative variance fraction at which the worker stops retaining principal components (0.95 = retain enough components to explain 95% of input family variance). Higher values keep more components and capture finer detail; lower values produce smoother but less faithful draws.
   * - Enforce Monotonic (Non-Decreasing)
     - enforce_monotonic
     - select
     - no
     - 
     - When 'yes', each generated curve is clamped to be non-decreasing along x. Required for MAT_024 / hardening-curve material cards.
   * - Random Seed
     - seed
     - integer
     - 0
     - 
     - Integer seed for reproducible draws. 0 means choose a random seed; the actual seed is reported in the output for re-runs.
   * - Output Curve Name Prefix
     - output_name_prefix
     - scalar
     - mc
     - 
     - Prefix for generated curve names. Curves are named '<prefix>_0001', '<prefix>_0002', etc.

Outputs
-------

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

   * - Label
     - ID
     - Type
     - Description
   * - Generated Curves
     - generated_curves
     - vector
     - Curve group containing the N generated curves on the shared x-grid.
   * - Mean + 2 sigma Band + Generated Mean
     - mean_and_band
     - vector
     - Four-curve group for validating generation quality: input mean, generated mean (mean of the N generated curves), input mean + 2sigma, input mean - 2sigma. Overlay input mean and generated mean to confirm the generator preserved the central tendency of the input family.
   * - Seed Used
     - seed_used
     - integer
     - The random seed actually used (the input seed, or a randomly chosen seed if input was 0).
   * - Mean Agreement RMSE
     - mean_rmse
     - scalar
     - RMSE between the input pointwise mean and the generated pointwise mean. A low value (relative to the y-range of the curves) confirms the generator preserved the central tendency. Use as a quick quality gate.
   * - Status
     - status
     - string
     - Human-readable summary of the run: input count, grid size, sampling method used (pointwise / pca), PCA components retained (if applicable), monotonic flag, RMSE of mean agreement, seed.

.. raw:: html

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