Quickstart

This page covers the supported fast-start paths for McSAS3:

  • a 1D command-line workflow using YAML configuration files

  • a Python workflow built on canonical ProcessingData and DataBundle objects

Command-Line Quickstart

The maintained CLI path currently covers 1D source-data ingestion. A minimal end-to-end run from a source checkout looks like this:

  1. Run the optimizer:

mcsas3-runner \
  -f testdata/quickstartdemo1.csv \
  -F example_configurations/read_config_csv.yaml \
  -R example_configurations/run_config_spheres_auto.yaml \
  -r result.nxs \
  -d

  1. Histogram the stored repetitions and generate a PDF summary:

mcsas3-histogrammer \
  -r result.nxs \
  -H example_configurations/hist_config_dual.yaml

This produces:

  • result.nxs: the canonical HDF5 result file, including stored ProcessingData

  • result.pdf: the histogram/result summary generated by the histogramming step

Python Quickstart

For new scripts and notebooks, use the canonical top-level workflow API:

from pathlib import Path

from mcsas3 import (
    STAGE_CLIPPED,
    load_result_processing_data,
    optimize_processing_data,
    prepare_1d_processing_data_from_file,
    selected_bundle_from_processing,
)

processing = prepare_1d_processing_data_from_file(
    Path("testdata/quickstartdemo1.csv"),
    csvargs={"sep": ";", "header": None, "names": ["Q", "I", "ISigma"]},
    nbins=100,
    analysis_stage=STAGE_CLIPPED,
)

optimize_processing_data(
    processing,
    Path("result.nxs"),
    modelName="mcsas_sphere",
    fitParameterLimits={"radius": "auto"},
    staticParameters={"background": 0.0, "scale": 1.0, "sld": 33.4, "sld_solvent": 0.0},
    maxIter=1000,
    convCrit=1.0,
    nRep=2,
    nCores=1,
    logRandom=True,
)

restored = load_result_processing_data(Path("result.nxs"))
selected_bundle = selected_bundle_from_processing(restored)
print(selected_bundle["signal"].signal.shape)

With fitParameterLimits={"radius": "auto"}, McSAS3 derives radius limits from the selected Q support as pi / q_max for the lower limit and 2 * pi / q_min for the upper limit. logRandom=True is recommended for standard operation so sampled fit parameters are distributed log-uniformly across their configured range.

2D Note

The canonical Python workflow supports 2D preparation through:

  • prepare_2d_processing_data(...)

  • prepare_2d_processing_data_from_file(...)

The maintained CLI quickstart above is intentionally documented as a 1D path.

Next Steps

  • See Usage for the supported CLI, Python, and result-file workflows.

  • See Migration from McData* if you are updating notebooks that previously used McData*.

  • See Structure for the current module-structure overview.