Merge multiple --atomfile files; split gaussian_atoms.yaml

README.md

@@ -234,27 +234,39 @@ scaled by `volume_scale` — instead of building a Gaussian dummy from
 `radius`/`displaced_volume`. Every species present in the structure
 must define it when `--excluded per-kind` is selected.
 
+#### Merging multiple files
+
+Several form-factor files can be supplied and are merged in order — repeat
+`--atomfile` on the CLI, or pass a list to the Python constructor — letting
+you compose, e.g., a coarse-grained residue file with an atomic one. If the
+same species appears in more than one file the **last file listed wins** and
+a warning is logged. Merging happens before symbolic resolution, so an
+`!Alias` / `!United` / `!Linear` entry in one file may reference a species
+defined in another.
+
 ### Shipped form-factor files
 
 | File | Description | Best for |
 |------|-------------|----------|
 | `assets/foxs_formfactors.yaml` | Cromer-Mann (Int. Tables Vol. C) atomic form factors, FoXS-compatible volumes and SASA radii | Atomic PDBs with `--excluded foxs` |
-| `assets/gaussian_atoms.yaml` | Mixed table: residue single-bead polynomials plus atomic/united-atom Gaussians (CH/CH₂/NH/…) | Atomic PDBs with PepsiSAXS-style solvent models |
-| `assets/stovgaard2010.yaml` | Per-residue form-factor centroids (one-body model, q ∈ [0, 0.75] Å⁻¹) from Stovgaard et al. 2010, <https://doi.org/10.1186/1471-2105-11-429> | Residue / Cα single-bead models |
+| `assets/pepsi_atoms.yaml` | Atomic [Waasmaier-Kirfel](https://doi.org/10.1107/S0108767394013292) five-Gaussians + [PepsiSAXS](https://doi.org/10.1107/S2059798317005745) united-atom groups (CH/CH₂/NH/…), K = 4π | Atomic PDBs with PepsiSAXS-style solvent models |
+| `assets/stovgaard2010.yaml` | Per-residue form-factor centroids (one-body model, q ∈ [0, 0.75] Å⁻¹) from [Stovgaard et al. 2010](https://doi.org/10.1186/1471-2105-11-429) | Residue / Cα single-bead models |
 | `assets/poly_amino_acid.yaml` | Amino-acid bead polynomials with a separate `excluded_solvent` polynomial per bead | Cα / single-bead with `--excluded per-kind` |
 | `assets/poly_amino_acid_combined.yaml` | Amino-acid bead polynomials with the excluded solvent already folded into the form factor | Cα / single-bead with `--excluded disabled` |
 | `assets/poly_martini.yaml` | Martini-3 bead polynomials with a separate `excluded_solvent` polynomial per bead | Martini-3 CG with `--excluded per-kind` |
 | `assets/poly_martini_combined.yaml` | Martini-3 bead polynomials with the excluded solvent already folded into the form factor | Martini-3 CG with `--excluded disabled` |
 
-Gaussian files use b values in the standard s² = (q/4π)² convention
-(International Tables / Cromer-Mann). The atomic coefficients differ
-(Cromer-Mann vs Stovgaard-2010) and the volume/radius tables match
-their respective tools.
+Files using `!Gaussian` form factors (`foxs_formfactors.yaml`,
+`pepsi_atoms.yaml`) give b values in the standard s² = (q/4π)² convention
+(International Tables / Cromer-Mann), so published exponents can be used
+directly. Their atomic coefficients come from different parametrizations
+(Cromer-Mann for FoXS vs Waasmaier-Kirfel for Pepsi) and the volume/radius
+tables match their respective tools.
 
 **Don't mix files with non-matching `--excluded` flags.** Each
 YAML + excluded-volume convention is a self-consistent bundle:
 `foxs_formfactors.yaml` was calibrated jointly with FoXS's
-`K = 16π` Gaussian, while `gaussian_atoms.yaml` was calibrated with
+`K = 16π` Gaussian, while `pepsi_atoms.yaml` was calibrated with
 PepsiSAXS's `K = 4π`. Swapping the denominator gives atomic and
 excluded contributions that were never fit together and yields
 subtly biased intensities.
@@ -335,6 +347,9 @@ pripps --help
 # Debye formula (exact, O(N²))
 pripps -a atoms.yaml -i structure.pdb debye
 
+# Merge several form-factor files (last listed wins on duplicate species)
+pripps -a base.yaml -a overrides.yaml -i structure.pdb debye
+
 # Multipole expansion (linear in atoms, truncation auto-selected)
 pripps -a atoms.yaml -i structure.pdb multipole
 pripps -a atoms.yaml -i structure.pdb multipole --lmax 68  # fixed order