Dry thickness parameter

[rozyczko]

Dry Thickness Parameter

1. Motivation and physics

For a solvent-swollen layer (polymer brush, adsorbed polymer/protein film, lipid head-group region), the fitted layer thickness d is the wet (swollen) thickness.

The dry thickness

τ = d · (1 − φ)

where φ is the solvent volume fraction, is the thickness the adsorbed material
would occupy with all solvent removed. It matters for two reasons:

1. It is the experimentally known quantity. Dry-state ellipsometry, XRR, or QCM-D
   measurements of the same film give τ directly. Users routinely want to fix τ (or
   fit it inside a narrow window) and let the reflectometry fit determine how the
   material swells, i.e. fit d while φ follows from material conservation.
2. It is the physical quantity. τ is proportional to the adsorbed
   amount per unit area (Γ = τ·ρ_dry), which is what gets compared across contrasts
   and published. A multi-contrast fit that
   conserves τ across contrasts is far better constrained than one that fits d and
   φ independently per contrast.

Today users can only approximate this in a notebook via
easyreflectometry.constraints.constrain(φ, '1 - t/d', ...) with a standalone
derived_parameter for τ, but a standalone derived parameter cannot be saved. That
save-blocking limitation is the main motivation for first-class support: τ must be a
model-owned parameter, like Model.total_thickness already is.

2. Scope

• In scope (library): a dry_thickness parameter on solvated layers, i.e. any
  Layer whose material is a MaterialSolvated, which includes every
  LayerAreaPerMolecule, in two modes:
  • derived (default): read-only, τ tracks d and φ; usable in constraint and
    inequality expressions, shown in reports;
  • constrained: τ becomes an independent (fittable or fixed) parameter and
    φ = 1 − τ/d becomes the dependent one (material conservation).
• In scope (app): display of τ per layer in the Surfactant Layer assembly editor,
  a per-layer "constrain dry thickness" toggle, editing of τ when constrained, and
  automatic appearance of τ / dependent-φ in the Analysis parameter table.
• Out of scope (future work): volume-fraction-profile brush models (refnx-style
  Spline/VFP with conserved dry amount);
  dry thickness derived from molecular
  volume V_m / APM for LayerAreaPerMolecule (an alternative identity that would
  need molecular volume, which the model does not carry); per-contrast τ sharing UI
  (already achievable via existing user constraints once τ has a structural path).

3 Public API summary

Symbol	Kind	Behavior
Layer.dry_thickness	Optional[Parameter]	τ; None for non-solvated layers; read-only while unconstrained
Layer.is_solvated	bool	material is a MaterialSolvated
Layer.constrain_dry_thickness	bool property	swaps free parameter between φ and τ

4. Worked user stories

1. Report-only (default): user builds a surfactant model, fits d and φ per
   layer as today; the Sample table and the Summary report now also show
   τ = d(1−φ) with its propagated uncertainty (variance propagation comes free from
   easyscience dependent parameters). No behavior change to any existing fit.
2. Ellipsometry-informed brush fit: user measured τ = 48 Å dry. In the app:
   tick Constrain dry thickness, type 48 in the Dry d cell, leave τ fixed, free
   d. The fit explores swelling; φ follows conservation; a fit step proposing
   d < 48 is applied by the automatic inequality.
3. Multi-contrast: τ of the layer in model A constrained equal to τ in model B
   with the existing Constraints editor, while each contrast keeps its own d.