McSAS3GUI (v0.3.1)

McSAS3GUI is the desktop application for McSAS3. It guides you through loading SAXS/SANS data, previewing a model fit, running the Monte Carlo optimization, and turning the result into histograms.

If you are unfamiliar with Python environments, start with one of the two paths below. The rest of this README is mostly for people who want to script, customize, or build McSAS3GUI themselves.

Start Here

Option 1: Download the application

For prebuilt standalone binaries, see the latest GitHub release:

• https://github.com/BAMresearch/mcsas3gui/releases/latest

Release assets are built for tagged releases. This is the easiest path when a release is available for your operating system.

Option 2: Run with one uv command

If uv is installed, run:

uvx --python 3.14 --from mcsas3gui m3gui

The first run may take a few minutes. uvx creates an isolated Python environment, installs McSAS3GUI and McSAS3, and then starts the m3gui application. You do not need to create or activate a virtual environment.

If uv is not installed yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installing uv, close and reopen the terminal if the uvx command is not found.

Keep the command installed

For regular use from the terminal, install the GUI command once:

uv tool install --python 3.14 mcsas3gui
m3gui

First Run

1. Open the Getting Started tab.
2. Choose Quick Start demo from the template list.
3. Use the loaded example settings to preview the data and model.
4. Run the optimization.
5. Run histogramming to create the distribution plot.

The optimization produces an HDF5 result file. Histogramming adds distribution results to that file and writes a PDF plot next to it.

What the Tabs Do

• Getting Started loads complete example workflows.
• Data Loading tells McSAS3 how to read your data file.
• Run Settings sets the scattering model and optimization limits.
• McSAS3 Optimization runs one or more optimizations.
• Histogram Settings defines the distributions to calculate.
• (Re-)Histogramming recalculates histograms from existing optimization results, without rerunning the optimization.

Both optimization buttons are abortable. While running, they change to Running... Click to abort. and forward a stop request to the core McSAS3 runner.

Other Installation Options

McSAS3GUI requires Python 3.12 or newer. The examples in this README use Python 3.14, the current recommended runtime.

Install the released GUI package with pip:

pip install mcsas3gui

If you prefer a manually managed uv environment:

uv venv --python 3.14
source .venv/bin/activate
uv pip install mcsas3gui
m3gui

On Windows, activate the environment with .venv\Scripts\activate instead of source.

You can also install the in-development version with pip:

pip install git+https://github.com/BAMresearch/mcsas3gui.git@main

or, from a local source checkout with uv:

uv venv --python 3.14
source .venv/bin/activate
uv pip install ../McSAS3 .
mcsas3gui --version

Run the local source command from the McSAS3GUI repository with the McSAS3 repository checked out next to it.

After activating an environment, these launch commands all work:

mcsas3gui
m3gui
python -m mcsas3gui

Standalone GUI bundles

A standalone build path is available for local packaging and CI:

tox -e standalone

This produces a platform-specific standalone bundle under dist/standalone/, including the windowed McSAS3GUI app and the bundled mcsas3-histogrammer helper used by the histogramming tabs.

Linux standalone release artifacts are built in a manylinux_2_34 container so the produced bundle stays compatible with systems that provide GLIBC 2.34 or newer. Local Linux builds need the Qt xcb runtime packages listed in ci/requirements_linux.txt.

Standalone release process

Standalone release assets are produced by the GitHub Actions workflow in .github/workflows/standalone-release.yml.

The release workflow:

• checks out both McSAS3GUI and McSAS3
• runs tox -e standalone on Linux, macOS, and Windows, with Linux built from a GLIBC 2.34 baseline
• signs the macOS .app bundle with a Developer ID certificate
• notarizes and staples the macOS bundle with notarytool and stapler
• uploads the platform zip archives to the GitHub release

For local development builds, tox -e standalone produces the same bundle layout, but notarization only happens in the release workflow because it requires GitHub secrets and Apple credentials.

GitHub secrets for macOS standalone releases

The macOS release build requires these GitHub Actions secrets:

• MACOS_CERT_P12_BASE64
• MACOS_CERT_P12_PASSWORD
• MACOS_CODESIGN_IDENTITY
• MACOS_KEYCHAIN_PASSWORD
• MACOS_NOTARY_KEY_ID
• MACOS_NOTARY_ISSUER_ID
• MACOS_NOTARY_API_KEY

You can prepare all of them in one step with:

tools/prepare_github_secrets.sh \
    --p12-path ~/Downloads/mcsas3gui-signing-cert.p12 \
    --p12-password '<p12-password>' \
    --p8-path ~/Downloads/AuthKey_ABC123XYZ.p8 \
    --issuer-id 12345678-1234-1234-1234-123456789abc

The helper script:

• base64-encodes the .p12 signing certificate as MACOS_CERT_P12_BASE64
• reuses the supplied .p12 password as MACOS_CERT_P12_PASSWORD
• imports the .p12 into a temporary macOS keychain to discover MACOS_CODESIGN_IDENTITY
• emits MACOS_KEYCHAIN_PASSWORD for the temporary runner keychain used in CI
• reads the raw .p8 contents into MACOS_NOTARY_API_KEY
• infers MACOS_NOTARY_KEY_ID from AuthKey_<KEYID>.p8 when possible
• requires MACOS_NOTARY_ISSUER_ID explicitly because Apple does not store it in the .p8 file

Store the emitted values in GitHub under Settings, Secrets and variables, Actions.

Example Files

The shipped example configurations live under:

• src/mcsas3gui/configurations/readdata
• src/mcsas3gui/configurations/run
• src/mcsas3gui/configurations/histogram
• src/mcsas3gui/configurations/prefab

The shipped example datasets live under:

• src/mcsas3gui/testdata

Read configurations declare source data units with QUnits: "1/nm" and IUnits: "1/(m sr)". Run configurations keep logRandom: true enabled, which is the recommended standard mode for log-uniform parameter sampling.

Structure

The GUI is organized into:

• gui/main_window.py for tab assembly
• gui/*_tab.py modules for tab-specific UI behavior
• gui/mcsas3_bridge.py for canonical McSAS3 integration
• gui/optimization_worker.py and utils/base_worker.py for background execution
• shared GUI helpers in gui/*_helpers.py and utils/task_runner_mixin.py

The generated dependency overview is documented in the GUI structure page.

Documentation

https://BAMresearch.github.io/mcsas3gui

Development

Contributing

We welcome contributions! Please ensure your code follows the project's coding style and includes relevant tests and documentation.

License

This project is licensed under the MIT license

Testing

See which tests are available (arguments after -- get passed to pytest which runs the tests):

tox -e py -- --co

Run a specific test only:

tox -e py -- -k <test_name from listing before>

Run all tests with:

tox -e py

Package Version

Get the next version number and how the GIT history would be interpreted for that:

pip install python-semantic-release
semantic-release -v version --print

This prints its interpretation of the commits in detail. Make sure to supply the --print argument to not raise the version number which is done automatically by the release job of the GitHub Action Workflows.

Project template

Update the project configuration from the copier template and make sure the required packages are installed:

pip install copier jinja2-time
copier update --trust --skip-answered

CHANGELOG

v0.3.1 (2026-09-11)

Bug fixes

• fix: improving flat background fitting, and sasmodels parameter value clarity. (03543ac)

• fix: make sure the resolved CLI is up to date for histogramming as well. (edc0fff)

• fix: fix Qt race issue and prevent mixed-version McSAS3+McSAS3GUI operation (6df2aaa)

• fix: missing maxAccept would cause issue. (17ed25e)

Continuous integration

• ci: fix fixtures (9751469)

v0.3.0 (2026-09-11)

Bug fixes

• fix: small usability fixes (f5ac8f4)

Enh

• enh: adding a porod-slope background option to the minimizer and plot (df4eade)

Unknown Scope

• doc: update README for friendlier introduction (75e7936)

• Update README.md (7402614)

v0.2.1 (2026-08-26)

Bug fixes

• fix: fix for CI/CD issue (b835e64)

• fix: clear stale prefab file selections when switching examples (c8e2529)

Unknown Scope

• Same behaviour implemented for the histogramming tab. (f244087)

• ensuring previous examples are removed from the optimization tab when another example is chosen (eda6924)

• doc: mentioning the structure factor applied to the form factor in the Round Robin dataset 3 example (1d70ff1)

v0.2.0 (2026-08-25)

Bug fixes

• fix: ruff (9eb7bd1)

• fix: do not restrict the PyQT version (was only necessary for old linux) (771be52)

• fix: ruff fix (04b2ec3)

• fix: improved dependencies for the current RHEL-based linuxes. May need to be revisited later. (045e9ad)

• fix: updates for notarization (4005ccd)

• fix: adjusting CI so we can run with the in_depth_upgrades branch of McSAS3 (0ec6b15)

Continuous integration

• ci: de-duplicate macOS codesign by realpath and reduce log noise (9adc2fe)

• ci: de-duplicate macOS codesign by realpath and reduce log noise (f9e0193)

• ci: de-duplicate macOS codesign by realpath and reduce log noise (29d6955)

• ci: de-duplicate macOS codesign by realpath and reduce log noise (5c219d2)

• ci: de-duplicate macOS codesign by realpath and reduce log noise (b144e01)

• ci: handle non-canonical macOS framework signing in release workflow (63a0cf9)

• ci: skip direct file signing inside macOS bundles (3819d88)

• ci: fix macOS codesign ordering in standalone release workflow (b9b9942)

• ci: add standalone release workflow (efdfc21)

• PyPI: fix pypi url, switch to actions/checkout@v5 (ea8998e)

• PyPI: copier template update other places to pypi.org as well (5b00873)

• PyPI: move from test.pypi.org to pypi.org (97d72f2)

Enh

• enh: added python3.14 to tox tests (71f9689)

• enh: build standalone versions for three plarforms (7fb84b8)

Testing

• Style: checks moved to early tests stage (9f722d5)

Unknown Scope

• Fix for Linux build (08b72ec)

• track main branch of McSAS, no longer in_depth_upgrades (ffaccef)

• Bump the GLIBC version requirement of Linux to a more modern version to avoid limiting ourselves to old PyQT versions (e6f812d)

• simulated data now will use automatic porod slope determination for extrapolation (bad6e19)

• simulated data now will use automatic porod slope determination for extrapolation (0956ead)

• modified README to add a uv installation path (28b839f)

• documentation and default configuration updates (edd3c7f)

• doc: Updated build release documentation (9685a5d)

• Fixes to binary build scripts (f623285)

• added notarization (fbc0ba6)

• trying a different approach (62c34e8)

• patching workflows (88d28cb)

• fix for seed issue (d31867a)

• setting up for code signing for mac os x in CI (c7a4043)

• fix build paths (c14d483)

• yet another test fix. (e50848b)

• fix to imports, shifting python to match modacor reqs. (9baed9c)

• addressing small usability issues. (9fad697)

• fixing small documentation issue (25065ea)

• bugfixes in compiled build (5d52e4b)

• bugfix (f3c1729)

• compiled McSAS3GUI (2a3b138)

• aux windows close when main closes (6bf68db)

• bugfix (524db9f)

• documentation generation (fc0d7d0)

• typing/docstrings added (26c1d4e)

• more cleanip, moving on to docs next (7058012)

• more cleanup (3f48b72)

• next cleanup step (b36da89)

• more cleanup (f63560e)

• another cleanup sweep (2051dfb)

• continuing cleanup (a7ff42f)

• cleanup pass and tests (de4dda8)

• initial cleanup pass on McSAS3GUI (95dd184)

• adjusting the test configuration (82c2c20)

• stop button on test run too. (cdd39cf)

• implement stop functionality (1fc1bba)

• adjusted ignores and added missing info (f6f954b)

• adjust gitignore (f598571)

• adapting to the new API of McSAS3 with ProcessingData (d3243ac)

• basic formatting and project git hooks, we'll pick this up after we're done with McSAS3 upgrades. (192e829)

v0.1.6 (2025-09-05)

Bug fixes

• RunSettingsTab: show helpful info for simulation model (2b72793)

Unknown Scope

• enhancement(PreFab): Added an example using simulated base model data. (1948f8d)

v0.1.5 (2025-09-05)

Bug fixes

• Histogramming: actually use new input/ouput paths given to hist_run_tab (51398b2)

Unknown Scope

• Update on logo (c82daec)

v0.1.4 (2025-08-15)

Bug fixes

• HistogramSettingsTab: set expected output file, do not use (not working) paths from prefab (a0c59ab)

• GettingStartedTab: test aginst the tab which is to be modified (0c35ce0)

Code style

• General: formatting (2d97002)

v0.1.3 (2025-08-14)

Bug fixes

• PreFab: output files from testdata written to temp directory as well (0fd0442)

• RunSettingsTab: use the same temp dir in run_test_optimization() (7ac2399)

• GettingStartedTab & Logging: create a proper temp dir out-of-source for log files and intermediate configs (a4b5bdf)

• DataLoadingTab: csvargs is expected as dict in McSAS (209dc62)

• Configurations Examples: moved to src dir since they need to be installed along (e75c5a6)

• Project: remove redundant dependencies implied by mcsas3 (2e550ef)

Continuous integration

• Publish: show verbose messages in case of error (35c0bed)

• Tests: testing Windows (5ff1ebc)

• Publish: pypi url needs /legacy/ suffix (15121e8)

• Publish: use test.pypi.org (505c64a)

v0.1.2 (2025-08-13)

Bug fixes

• Project: McSAS3 dependency available on PyPI now (cf280f8)

Code style

• General: formatting improved (9159f96)

Continuous integration

• Release: debug job (82c1952)

• Docs: update package DB here as well (0496071)

• Tests: before installing sys packages, update package DB, to avoid outdated lists (e00a085)

• Tests: try installing PyQt6 system-wide to get all required binary dependencies (be3e5f5)

• Tests: typo installing additional system packages required by PyQt6 (909c208)

• Tests: additional system packages required by PyQt6 (9584c29)

Unknown Scope

• Revert "ci(Release): debug job" (e3fd4ed)

• tests(Utils): remove unused code which causes import errors (c407196)

v0.1.1 (2025-08-12)

Unknown Scope

• 0.1.1 (29a34cc)

• Last example: RR dataset 3 (210889e)

• will work on 3.10 as well. (4ed299e)

• modern numpy now works as well, removing restriction on python 3.13 (86cf44b)

• Extra explanation (400c602)

• Updates to the examples (bb33ec8)

• Adjustment to the advanced nexus demo (highlighting logRandom), and addition of the round robin 1 demo (6fa5d84)

• adding logo (49e14da)

• improved structure of eventFilter. Still allows internal drag and drops though. (d9e0025)

• Fixing table highlight color (02a7232)

• Drag and drop fix for the file table widgets. This was hard. (28036da)

• Add drag-and-drop support for files into the tables. (02b8009)

• last one (3014af0)

• Ok, windows is a pain in the butt. (800965f)

• Applying some style to override Window's dark defaults. (20572e9)

• Stopped messing around with fonts as they're not consistent cross-platform. (0ba0b09)

• minifix. (3281589)

• Changing debug levels (0f2cd55)

• Improving the text on the three examples. (166ee4f)

• New nexus example, and an update to the configuration files (9d67def)

• Update order and text. (d049a36)

• showing the test histogram PDF, even on Windows (2b7119f)

• Trying to get the PDF to show on Windows. (0cd3889)

• Bug fixes for windows (1d21d51)

• making sure we can plot the test histogram also in windows (4fa9b37)

• minifix (519335e)

• Can load prefabricated examples from a single yaml (6dcdc12)

• Removing too challenging nexus data from the test data. (6e6a379)

• updating getting started. (e0a138e)

• correcting file extension of processed files to .hdf5 (606d5d1)

• fixing a path issue on windows (d6c6783)

• prevent breaking on windows with empty model name (75c0cb3)

• Ensure that the default configurations are loaded from the correct path (b87a922)

• fixed annoying window repositioning issue (5446eaf)

• Fixing small usability issue - launch with python -m mcsas3gui (7b56ae6)

• Change the way mcsas3 is launched to avoid command-line scripts. (008f094)

• enforcing posix paths on CLI (2f3c3ee)

• Updated pyproject fixing bug (a44d922)

• small update (02b6018)

• pyinstaller --name McSAS3GUI --windowed src/mcsas3gui/main.py # not yet fully functional executable (7986876)

• updated pyproject towards build (34128cd)

• reorganisation to enable pip installability, resulting in command-line m3gui (63a0795)

• connecting signals to set saved config files in the optimization and histogramming tabs (411d120)

• Updating pulldown menus on save (ab2a492)

• A readme and a license (477e819)

• updated requirements to remove particular mcsas3 commit (3654674)

• handling of IEmin in data settings tab (16a2b55)

• Minor edits for readability (5aa460b)

• Adjusting the yaml display and saving with a custom dumper (967be91)

• Fleshing out the "Getting Started" helpful bits. (e109fd6)

• Clearer plotting when using omit (2d5639e)

• Test histogram now opens PDF automatically. (c815eeb)

• Histogramming works and editor works.. (1f9afb0)

• fix file extensions (48cdc8f)

• Drag and drop file line entry widgets now all working. (7fe3e2d)

• Abstracted the file line selection widget (1364400)

• Adding a reusable file-line selection widget with drag and drop (9ef410a)

• bug resolved with spaces in filenames. (e36b7ee)

• Trying to get drag and drop working in the file tabulation widget (5dc689c)

• Updates... (dd65ab4)

• separated the file selection table for optimization and histogramming (90da9e6)

• setting previously used directories for user convenience (0731646)

• cleanup (dfbfe61)

• editor now functional for multipart yamls (needed for histogramming) (1e7f061)

• Getting there.. (e9224e1)

• updates. (2948074)

• Somewhat functional, processes cannot be killed yet, however. (8e2a449)

• Now can run and show a test optimization (983f12c)

• Setting up test runs in run_settings tab. (30f5033)

• updating run settings (73b8279)

• Updates to data loading, I think it works for now. (be9fd17)

• upgrades (24cae6d)

• working ok now. (3b43344)

• data loading tab starting to look like something useful now. (8a4e925)

• Now loads and plots (0d7dc3c)

• minimal change in naming. (3859dcd)

• Updated main window naming (20b0063)

• Drafted the optimization tab contents (d3b1e89)

• some additions, but nothing working yet (41acbd8)

• sasmodels automatically interpreted (b11ae97)

• run config now working with central yaml editor. editor has syntax highlighting and syntax error tooltips. (1d02a85)

• Centralizing the yaml editor widget (8cc2761)

• sort of working (0bfbf07)

• first commit (5fcbc09)