==========
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:

.. code-block:: bash

   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

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

.. code-block:: bash

   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:

.. code-block:: python

   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 :doc:`usage` for the supported CLI, Python, and result-file workflows.
- See :doc:`migration` if you are updating notebooks that previously used ``McData*``.
- See :doc:`structure` for the current module-structure overview.