Run Case A, one step at a time

Get the project and open a terminal

This tutorial follows Case A only. Start by reproducing the archived example; only then inspect the later refined Case A and conditional parameter ranges. The website itself displays saved results and does not run Python.

You need a local computer with disk space for the repository and newly generated results, a terminal, and a Conda installation available in that terminal. On Windows use Anaconda Prompt; on macOS/Linux use Terminal with Conda initialised. Keep this checkout separate from any active long-running calculation.

Choose one download route:

• Git: if Git is installed, run the two commands below.
• No Git: open the repository, select Code → Download ZIP, extract the entire archive, then open a terminal in the extracted tde-dust-echo-main folder. Do not run files from inside the ZIP.

git clone https://github.com/OlenaKompaniiets/tde-dust-echo.git
cd tde-dust-echo

For the ZIP route, use cd with your actual extracted folder. Quote a path containing spaces. On Windows Anaconda Prompt, cd /d "C:\your-folder\tde-dust-echo-main" also switches drives; replace the example path.

Checkpoint: the current folder contains environment.yml, tools, src, data, configs, STARS_library-master and examples. All later commands are run from this repository root, not from docs or a script subfolder.

Install dependencies and verify inputs

First confirm Conda is available, then create the dedicated environment once:

conda --version
conda env create -f environment.yml
conda activate ugc-dust
python --version
python tools/check_install.py

If ugc-dust already exists from this project, activate it; do not repeatedly recreate it. After reopening the terminal, activate it again before running Python. If Conda is not recognised, first install/initialise Conda or reopen the correct Conda-enabled terminal. Do not paste these commands into the Python >>> prompt.

environment.yml requests Python 3.11 and NumPy, SciPy, pandas, Matplotlib and Astropy. It specifies minimum dependency versions, not a frozen environment. The repository's historical VALIDATION_RELEASE.json records a separate Linux/Python 3.12 test; that is not a claim of a new test on your machine.

Expected: installed package versions, STARS histories: 141, and PASS. This checker verifies the bundled scientific-input hashes and does not start radiative transfer. If it reports missing packages, check environment activation. For a missing/changed input, restore the original file or investigate the intended change; do not bypass checks or edit reference hashes just to obtain PASS.

Understand the bundled observations and configuration

The inputs are already included. For this example you do not need to obtain new observations, download the STARS library again, or edit a data table.

In the CSV, mjd is observer time; F_W1_Jy/F_W2_Jy are total measured fluxes. The sigma_..._Jy columns are the effective uncertainties used directly, already including the adopted approximately 1.10 mJy floor. Do not add that floor again. Fixed host columns are in mJy, not Jy: W1 8.0723159840 and W2 5.2154145825. Do not pre-subtract the host from the CSV; the likelihood handles it.

The configuration specifies graphite grains, compact dust at 0.25–0.50 pc and extended dust at 1–2 pc. Optical depths are dimensionless; viscous time is in days and angles in degrees. Leave the configuration unchanged for reproduction. Active transport resolution is reported under summary.json → numerics; legacy fields in the configuration are not all active grid settings. See input definitions and physical model.

Verify the stored Case A before computing

python tools/check_saved_case.py

This quick check reconstructs χ² from the stored observed fluxes, predictions and errors in examples/case_a/epochs.csv. It does not run the RT solver or refit parameters.

W1  19.4879842481
W2  39.4626564756
PASS chi2 = 58.9506407237 nominal conditional dof = 37

Printed final digits may differ slightly. An assertion failure or missing file should be investigated before the expensive step. The 37 nominal conditional degrees of freedom are 44 band measurements minus seven continuous fitted quantities, under fixed driver/geometry/grain assumptions. They do not account for the complete model-selection process.

Version checkpoint: this beginner reproduction target is the archived Case A with χ²≈58.95064. The later refined Case A has χ²≈58.83195 and a different parameter configuration. Do not compare a run of the old configuration against the refined target.

Run one archived physical model

Only after both checks pass, run:

python -u tools/run_case_a.py --plots

The wrapper checks installation, invokes the unchanged solver with --resolution fine and configs/case_a.json, and creates a new timestamped folder such as results/case_a_.... This is one fixed-configuration calculation, not a parameter search, grid or profile-uncertainty run.

Leave the terminal open. Progress includes transport/thermal calculations and W1/W2 output. Wait for the final Output:, chi2: and Difference from archive: messages and return to the shell prompt. The historical Linux test took about 171 s in the solver; your runtime and memory use can differ substantially. Do not launch another copy merely because a step is quiet.

--plots also creates saved thermal products and corrected thermal figures. If you want to omit that optional plotting step, use python -u tools/run_case_a.py. For this tutorial keep --plots: it also writes epochs.csv required for the next saved-case check. Without plots, inspect summary.json and response.csv; the epoch-table check and thermal-figure step are unavailable.

If interrupted, retain the partial directory for diagnosis. Repeating this wrapper starts a new timestamped directory; it does not automatically resume that interrupted directory. Do not overwrite or delete provenance to suppress a mismatch.

Find, check and interpret your output

Copy the exact folder printed after Output:. In your file manager, open it under the repository's results directory.

Recheck the newly generated epoch table with the actual folder name (replace the placeholder before running):

python tools/check_saved_case.py --folder results/PASTE_YOUR_CASE_A_FOLDER

Inspect together: total/band χ² and t0_boundary; actual numerics; thermal-iteration residuals; static_opacity_gate_passed; energy balance. Archived reference values are Tmax≈1143.58 K and escaping IR energy≈5.30131×10⁵¹ erg. The historical fresh-environment reproduction gave χ²=58.95133488, about0.00069416 above the archive; investigate materially larger differences before interpreting them.

A small energy residual tests the numerical energy ledger, not uniqueness of the geometry or resolution-converged parameter intervals. Saved summary.json status text can contain legacy candidate wording; interpret it together with the actual checks, not as a confidence-interval certificate.

Use figures and inspect the refined Case A

The plotting wrapper already calls the thermal-figure tool. To rebuild figures from existing arrays without fitting, use the archived example:

python tools/plot_thermal.py --folder examples/case_a

Or replace that folder with your completed plotted result. Use corrected files in thermal_publication_v2; do not use legacy thermal plots for scientific interpretation. The online explorer always displays saved archived Case A, not your newly computed local result.

The later refined Case A is a separate saved configuration with χ²=58.83195387879388. Read its config/summary/response/provenance first. The dated supplement does not include every thermal array or a full inference cache.

Optional, after reproducing the archive: the solver's existing command-line interface can evaluate the refined configuration directly. Use a new, unused output directory:

python -u V48_LOCAL_PAIR/solver.py --resolution fine --config analysis/v48_refined_2026-10-14/results/case_a/reference/config.json --output results/case_a_refined_01 --plots

This evaluates a saved refined point; it does not repeat the optimisation that found it. If that output name already exists, choose another. Run the epoch-table check from step6 on that folder and compare against the refined summary, allowing for documented environment differences. The direct solver does not call the corrected-figure helper; for corrected thermal plots subsequently run python tools/plot_thermal.py --folder results/case_a_refined_01. This optional command was checked against the interface; no new RT calculation was performed for this guide.

Understand conditional variations before launching inference

Start with the saved result, not a new grid. Inspect the twelve direct Case A endpoint configurations and the method explanation. The six physical parameters each have lower/upper candidates; Δχ² values are 0.957856–1.041510 relative to the refined Case A reference. These are approximate conditional parameter-variation intervals, not calibrated comprehensive 1σ errors.

1. Identify the refined Case A reference and the same observations, host values, error model and numerical resolution.
2. For a physical parameter of interest, hold it fixed and optimise the other five physical parameters plus t₀ on an approximation to saved RT responses.
3. Locate candidate endpoints near Δχ²=1. Check optimisation/extrapolation and lower minima.
4. Evaluate the selected configurations with direct RT, reoptimising t₀ but retaining the other physical parameters chosen by the approximation.
5. Compare the direct Δχ² to the case's direct reference, and report approximation/resolution/coverage limits explicitly.

Fresh-download boundary: the current supplement provides original scripts and selected scientific products, not all training caches, seed/checkpoint state, plans and original layout required to regenerate the entire profile analysis. Therefore there is no honest universal “next command” that finishes the conditional intervals from a clean checkout.

For a restored original research workspace, the historical sequence was V48_RESPONSE_VALIDATION (response approximation and first direct checks), V48_PROFILE_UPDATE (updated response profiles), then V48_PROFILE_FINAL_CHECK (fixed candidate checks). Before using any runner, restore its original supporting files and sibling modules, check the required Python/NumPy environment and all source/data fingerprints, and confirm that no other coordinator uses the same cache. The source copies in the dated supplement must not simply be launched in place as a complete installed project.

Only once that workspace has been restored and the original final-check plan is present, its supported preflight command is:

python -u V48_PROFILE_FINAL_CHECK/run_validation.py --check-only

After that check succeeds and you deliberately allocate a calculation budget, the historical fixed-plan invocation is:

python -u V48_PROFILE_FINAL_CHECK/run_validation.py --workers 4 --minutes 60

These are conditional original-workspace instructions, not commands for an untouched fresh repository. The 60 minutes setting is a session budget, not a promised duration; this run checks 13 planned configurations, not full direct nuisance-parameter profiles. Preserve reports and checkpoints. Do not relax a failed runtime/fingerprint guard.

Do not automatically start the broad staged grid after the tutorial: it can schedule thousands of evaluations. Existing code has caching and parallel workers, but the safe worker count depends on available RAM and CPU. Benchmark one model first. A cluster may increase throughput; optimisation, profiling and careful reuse may also help. Neither proves interval coverage or removes model assumptions. Future improvements are possibilities, not promised implemented features.