Outputs & Diagnostics --------------------- Each run writes enough metadata to inspect the construction afterwards. The most important files are under ``ROQ_data`` and ``Plots``. .. rst-class:: jenpyroq-doc-figure-container .. figure:: _static/jenpyroq_diagnostics.svg :alt: Diagram of JenpyROQ output files and diagnostics. :class: jenpyroq-doc-figure Run Directory ~~~~~~~~~~~~~ Before the ROQ object is initialised, the command creates the base output directory. It contains: * ``JenpyROQ.log``; * the copied configuration file; * ``git_info.txt``; * ``ROQ_data/``, including ``ROQ_metadata.txt``, ``full_frequencies.npy`` and the ``linear/`` and ``quadratic/`` array directories; * ``Plots/``, including ``Basis_parameters/`` and ``Waveform_comparisons/``. The config file is copied into the run directory so the stored arrays can be traced back to the exact input settings. ``JenpyROQ.log`` records parsed configuration values, default markers, basis construction progress, outlier counts, validation settings and timing information when ``timing = 1``. ``git_info.txt`` records the active git branch, latest commit hash, configured git author and current diff. This file is written at config-read time. ROQ Arrays ~~~~~~~~~~ The ``linear`` and ``quadratic`` subdirectories use the same file naming pattern, with ``linear`` or ``quadratic`` inserted in the filename. .. list-table:: :header-rows: 1 :widths: 38 52 * - File - Meaning * - ``preselection__basis.npy`` - Basis vectors produced by the pre-selection loop. * - ``preselection__basis_waveform_params.npy`` - Parameter points associated with pre-selection basis vectors. * - ``preselection__basis_residual_modula.npy`` - Largest projection residual found at each pre-selection step. * - ``basis_.npy`` - Enriched basis stored during the ROQ construction loop. * - ``basis_waveform_params_.npy`` - Parameter points associated with enriched basis vectors. * - ``basis_interpolant_.npy`` - Matrix used to reconstruct full-grid waveforms from empirical-node samples. * - ``empirical_frequencies_.npy`` - Physical frequencies selected as empirical interpolation nodes. * - ``empirical_nodes_.npy`` - Integer indices of those frequencies on ``full_frequencies.npy``. The top-level ``ROQ_metadata.txt`` stores: .. code-block:: text f-min f-max seglen The top-level ``full_frequencies.npy`` stores the original construction grid. Reduction Factor ~~~~~~~~~~~~~~~~ The log reports: .. code-block:: text basis reduction factor: (Original freqs [N_full]) / (New freqs [N_roq]) = N_full / N_roq This is a grid-size reduction diagnostic. The realised parameter-estimation speedup also depends on likelihood implementation, waveform-call cost, interpolation overhead and I/O. Diagnostic Plots ~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 42 48 * - Plot - Interpretation * - ``Plots/Preselection_residual_modulus_.pdf`` - Largest projection residual retained during pre-selection. * - ``Plots/Empirical_interpolation_error_.pdf`` - Maximum interpolation error recorded while adding enriched basis elements. * - ``Plots/Number_of_outliers_.pdf`` - Number of training points above the current cycle tolerance after each enrichment step. * - ``Plots/Frequencies_.pdf`` - Histogram of empirical frequencies. * - ``Plots/Interpolation_errors_random_test_points_.pdf`` - Post-construction validation errors on random test points. * - ``Plots/Representation_error_hp_.pdf`` - Fractional reconstruction error for ``h_+`` at the configured ``[Test_values]`` point. * - ``Plots/Representation_error_hc_.pdf`` - Fractional reconstruction error for ``h_x`` at the configured ``[Test_values]`` point. * - ``Plots/Waveform_comparisons/Waveform_comparison_*_.pdf`` - Full-grid waveform, ROQ reconstruction and empirical-node samples. * - ``Plots/Basis_parameters/Basis_parameters__.pdf`` - Distribution of parameter values selected for basis elements. Post-Processing Only Mode ~~~~~~~~~~~~~~~~~~~~~~~~~ Set: .. code-block:: ini [I/O] output = existing_run_directory post-processing-only = 1 In this mode the code skips construction and loads: .. code-block:: text ROQ_data//empirical_frequencies_.npy ROQ_data//empirical_nodes_.npy ROQ_data//basis_interpolant_.npy ROQ_data//basis_waveform_params_.npy If an old run lacks ``empirical_nodes_.npy``, the code recovers node indices by searching ``full_frequencies.npy`` for the stored empirical frequencies. Practical Checks ~~~~~~~~~~~~~~~~ Before using a basis in inference, inspect: * validation errors relative to ``tolerance-lin`` and ``tolerance-qua``; * whether outlier counts reached the requested values in every enrichment cycle; * empirical-frequency histograms for unexpected clustering at boundaries; * waveform-comparison plots for the configured ``[Test_values]`` point; * basis-parameter histograms for gaps in the intended training domain.