rozyczko · Oct 19, 2026 · Mar 23, 2026 · Apr 13, 2026 · Apr 27, 2026 · Apr 30, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
diff --git a/README.md b/README.md
@@ -9,13 +9,41 @@
   </picture>
 </p>
 
-**EasyReflectometry** is a software for performing reflectometry
-calculations based on a layer model and refining its parameters against
-reflectometry data.
+**EasyReflectometry** is a Python library for simulating reflectometry
+profiles from layered sample models and refining their parameters
+against experimental data.
+
+It supports multiple contrasts and simultaneous fitting, polarised
+reflectometry channels, Bayesian (MCMC) analysis, ORSO data and model
+import/export, and a choice of calculation engines (refnx or refl1d).
 
 <!-- HOME REPOSITORY SECTION -->
 
-**EasyReflectometry** is developed as a Python library.
+**EasyReflectometry** is built on the
+[EasyScience framework](https://easyscience.org) and maintained by the
+[European Spallation Source (ESS)](https://ess.eu).
+
+## Installation
+
+**EasyReflectometry** requires Python 3.11–3.13 and is available on
+PyPI:
+
+```bash
+pip install easyreflectometry
+```
+
+The `dev` extra is only needed if you want to contribute to the library
+or build the documentation. It adds the tooling for testing (pytest),
+linting and formatting (ruff, pre-commit), building the docs (mkdocs)
+and running the tutorial notebooks. To install it from PyPI:
+
+```bash
+pip install 'easyreflectometry[dev]'
+```
+
+See the
+[Installation & Setup](https://easyscience.github.io/reflectometry-lib/latest/installation-and-setup)
+guide for the recommended Pixi-based setup.
 
 License:
 [BSD 3-Clause](https://github.com/easyscience/reflectometry-lib/blob/master/LICENSE)
@@ -27,7 +55,7 @@ License:
 - 📖
   [Documentation](https://easyscience.github.io/reflectometry-lib/latest)
 - 🚀
-  [Getting Started](https://easyscience.github.io/reflectometry-lib/latest/introduction)
+  [Getting Started](https://easyscience.github.io/reflectometry-lib/latest/installation-and-setup)
 - 🧪
   [Tutorials](https://easyscience.github.io/reflectometry-lib/latest/tutorials)
 - 💬

diff --git a/docs/docs/api-reference/contrasts.md b/docs/docs/api-reference/contrasts.md
@@ -0,0 +1,75 @@
+# Contrasts
+
+A contrast is one structure measured under another SLD condition: the
+same film in D2O and in H2O, or a monolayer with deuterated and
+hydrogenated tails. Each contrast is an ordinary `Model`, with its own
+scale, background and resolution; what the contrasts have in common is
+shared in one of two ways:
+
+- **by identity**: an assembly or material is one object used by several
+  models, so it has one set of parameters;
+- **by equality**: a parameter of one model follows the corresponding
+  parameter of another, where the objects must differ (a hydrated layer
+  whose solvent differs between contrasts).
+
+The `Project` offers two routes to that state. **Adding a contrast**
+derives a new model from a reference with `derive_contrast`: assemblies
+the substitutions do not touch are shared, touched ones are copied with
+every parameter tied to the reference's except those of the replacement.
+
+```python
+from easyreflectometry.contrasts import ReplaceFormula
+from easyreflectometry.contrasts import ReplaceMaterial
+
+h2o_index = project.add_contrast(0, 'Film in H2O', [ReplaceMaterial(d2o, h2o)])
+h_tails = project.add_contrast(0, 'h-tails', [ReplaceFormula(tail_layer, 'C32H64')])
+project.parameter_models(film_layer.thickness)  # [0, 1, 2]: one parameter of three models
+```
+
+**Linking contrasts** ties two models that exist already. Parameters
+correspond by their path within the model, so the models need the same
+layout: the same assemblies and layers, with materials of the same kind
+(a `MaterialDensity` and a plain `Material` do not correspond);
+`plan_link` raises `LayoutMismatch` otherwise. The plan changes nothing:
+each `LinkRow` says what linking would do with one pair of parameters
+(`'tie'`, `'skip'`, `'already_tied'`, `'conflict'`), and with the
+reason. Scale and background always stay per contrast. A material's
+chemistry (`CHEMISTRY`: SLD, density, scattering lengths) is
+`'undecided'` until `materials='tie'` or `materials='skip'` is given,
+since contrasts usually differ in it.
+
+```python
+plan = project.plan_link(follower_index, reference_index, materials='skip')
+[(row.path, row.action, row.reason) for row in plan.rows]
+record = project.apply_link(plan)  # ties the 'tie' rows, all or none
+project.unlink(record)  # restores each follower's value and bounds from before the link
+```
+
+`apply_link` refuses a plan with undecided rows, or one the project has
+outdated since it was made. `Project.detach` frees a shared parameter in
+one model, which then gets its own copy of the assembly. The derivation
+of each contrast, the links and the sharing are saved with the project.
+See the
+[contrasts tutorial](../tutorials/advancedfitting/contrasts.ipynb) for a
+worked example.
+
+<!-- prettier-ignore-start -->
+::: easyreflectometry.contrasts
+    options:
+      members:
+        - CHEMISTRY
+        - ReplaceMaterial
+        - ReplaceFormula
+        - derive_contrast
+        - substitution_candidates
+        - UnsupportedSubstitution
+        - plan_link
+        - LinkPlan
+        - LinkRow
+        - LinkRecord
+        - LayoutMismatch
+        - follows
+        - tie_corresponding
+        - snapshot
+        - restore
+<!-- prettier-ignore-end -->
diff --git a/docs/docs/api-reference/index.md b/docs/docs/api-reference/index.md
@@ -41,6 +41,14 @@ parameter free and are enforced as penalties on the BUMPS fit problem.
 - [Constraints](constraints.md)
 - [Inequality Constraints](inequality_constraints.md)
 
+## Contrasts
+
+One structure measured under several SLD conditions: deriving a contrast
+from a reference model, and linking the corresponding parameters of
+models built separately.
+
+- [Contrasts](contrasts.md)
+
 ## Bayesian Analysis
 
 Posterior analysis of a DREAM sampling run: convergence diagnostics,
@@ -108,3 +116,4 @@ Summaries of a project and its fit results, and the plotting helpers.
 
 - [Summary](summary.md)
 - [Plotting](plot.md)
+- [Volume Fraction Profile](volume_fraction.md)
diff --git a/docs/docs/api-reference/volume_fraction.md b/docs/docs/api-reference/volume_fraction.md
@@ -0,0 +1 @@
+::: easyreflectometry.sample.volume_fraction
diff --git a/docs/docs/installation-and-setup/index.md b/docs/docs/installation-and-setup/index.md
@@ -172,10 +172,10 @@ can be installed using `pip`. To do so, use the following command:
 pip install easyreflectometry
 ```
 
-To install a specific version of EasyReflectometry, e.g., 1.8.0:
+To install a specific version of EasyReflectometry, e.g., 1.9.0:
 
 ```txt
-pip install 'easyreflectometry==1.8.0'
+pip install 'easyreflectometry==1.9.0'
 ```
 
 To upgrade to the latest version: