Documentation status

This page was generated and edited with the assistance of an LLM and is still in development. It has not been fully vetted by the developer. Verify commands, UI labels, file paths, workflow descriptions, and scientific claims against the current code and your local workflow before relying on it.

If you notice an error, omission, or outdated guidance, please open an issue on GitHub.

Development section status

The Development section is still incomplete. Current pages are working notes for contributors rather than a fully vetted maintenance guide.

SAXS Contrast Mode

This page is the contributor-facing map for the contrast-enabled SAXS component workflow.

The design goal is simple: keep the contrast workflow fully separated from the legacy no-contrast SAXS builder except at explicit routing and reload seams.

Main code paths

The feature spans three layers:

• main SAXS UI routing
• contrast supporting-application workflow
• distribution-scoped persistence and reload

The main files are:

• src/saxshell/saxs/contrast/settings.py
• src/saxshell/saxs/contrast/representatives.py
• src/saxshell/saxs/contrast/mesh.py
• src/saxshell/saxs/contrast/electron_density.py
• src/saxshell/saxs/contrast/debye.py
• src/saxshell/saxs/contrast/ui/main_window.py
• src/saxshell/saxs/contrast/ui/structure_viewer.py
• src/saxshell/saxs/project_manager/project.py
• src/saxshell/saxs/ui/project_setup_tab.py
• src/saxshell/saxs/ui/main_window.py

Workflow stages

The current contrast flow is staged as:

1. representative-structure analysis per stoichiometry bin
2. retained mesh construction and electron-density estimation
3. contrast-scaled Debye trace generation
4. distribution-scoped artifact persistence
5. automatic main-UI reload of the saved contrast distribution

The main UI routes into the contrast workflow when the active component_build_mode is contrast. The no-contrast builder path remains the default for no_contrast.

Persistence model

Contrast mode uses the same computed-distribution system as the rest of the SAXS workflow, but the distribution identity includes the build mode. The saved distribution snapshot carries a contrast/ subtree alongside the usual SAXS component and prior files.

That subtree is expected to contain:

• representative_structures/
• screening/
• geometry/
• electron_density/
• debye/
• summary files copied at the contrast root for reopen convenience

The reopen path should read only from the saved distribution snapshot, not from the transient working folder in project/contrast_workflow.

Prior-weight behavior

No-contrast prior generation still maps stoichiometry bins to the original cluster-bin representative files.

Contrast-mode prior generation now maps stoichiometry bins to the saved representative-trace artifacts from the active contrast distribution. The bin weights still come from the observed cluster counts, but the trace linkage comes from the saved contrast summary.

Current simplifications

These are intentional and should be treated as explicit constraints unless a follow-up change is planned:

• one existing representative structure per stoichiometry bin
• no predicted-structure weighting in the contrast build path
• support-app UI currently defaults to the built-in neat-solvent estimate (H2O, 1.0 g/mL) rather than exposing the full solvent-settings surface
• the structure viewer is a workflow/inspection view, not a publication renderer

Test coverage

Focused coverage currently lives in:

• tests/test_saxs_ui.py
• tests/test_saxs_contrast.py

Those tests cover the mode selector, Tools-menu launch, representative analysis, electron-density backends, mesh/density reload, distribution identity, main-UI handoff, reopen behavior, and contrast-mode prior-weight mapping.