Skip to content

Move Fraser 4π/16π convention from EV enum into the YAML #2

Description

@mlund

Motivation

The Fraser excluded-volume Gaussian width depends on the calibration of the form-factor dataset, not on a user runtime choice:

  • assets/foxs_formfactors.yaml was calibrated jointly with FoXS's K = 16π Gaussian.
  • assets/single_bead.yaml was calibrated with PepsiSAXS / CRYSOL K = 4π.

Today the convention lives in the ExcludedVolume enum (Fraser vs FraserFoxs), and users have to pair the right --excluded flag with the right YAML. The README has a "don't mix" warning. Moving the convention into the YAML lets each dataset self-document its calibration; mismatches become impossible.

Proposal

Add a Fraser denominator field on form-factor entries (per-kind, or a single top-level header):

__fraser_denominator__: 50.27   # = 16π for FoXS; default 4π = pepsi
C:
  radius: 1.58
  displaced_volume: 16.44
  ...

Then:

  • ExcludedVolume::Fraser::dummies reads the denominator from the YAML (default 4π).
  • ExcludedVolume::FraserFoxs variant and --excluded foxs value are removed.
  • README "don't mix" warning becomes unnecessary.

SASA hydration knock-on

SASA places water dummies at atom centers, overlapping the per-atom Fraser EV Gaussians. For clean cancellation through the first form-factor minimum, the SASA water's q-decay should match the EV's denominator.

Once the YAML carries its Fraser convention, SASA can build a Fraser-width water at runtime using that convention and bulk water volume (≈30 ų). The YAML's literal H2O (Cromer-Mann) entry stays in use for grid and voronoi hydration where dummies sit on a shell — physically correct there.

A temporary experiment showed Fraser-width water cuts the single_bead + voronoi-EV + SASA pathology on SASDEM6 from χ²/N ≈ 52 to ≈ 32 (still worse than shell-placed schemes at ≈ 5, but physically consistent).

Estimated effort

~150 LOC:

  • AtomKind: optional fraser_denominator field (or top-level FormFactorMap::fraser_denominator).
  • ExcludedVolume::Fraser::dummies: read it, default 4π. Delete FraserFoxs.
  • Hydration::Sasa::dummies: build Fraser water from YAML convention.
  • Update foxs_formfactors.yaml header to declare 16π.
  • CLI ExcludedKind: drop Foxs value (or accept and warn for backward compat).

Final state

Variant EV denom source Hydration water source
Fraser EV YAML (per-kind or header)
SASA hyd Fraser water built at runtime, YAML's convention
Grid hyd YAML H2O (Cromer-Mann)
Voronoi hyd YAML H2O (Cromer-Mann)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions