Example: 3d particles on a 2d plane

doc/src/SUMMARY.md

@@ -39,6 +39,7 @@
   - [Grandcanonical ensemble simulation of ellipses (2D)](mc-examples/ellipse-gcmc-2d.md)
   - [Melt an ideal hexagonal structure of hexagons](mc-examples/crystal-stability.md)
   - [Multi-site patchy shapes](mc-examples/multi-site-patchy-shapes.md)
+  - [3D shapes confined to a 2D plane](mc-examples/capsules-on-a-plane.md)
 
 # Reference
 

doc/src/mc-examples/capsules-on-a-plane.md

@@ -0,0 +1,44 @@
+# 3D shapes confined to a 2D plane
+
+<script type="module">
+import init from 'https://glotzerlab.github.io/hoomd-rs/mc-examples/capsules-on-a-plane.js'
+{{#include ../../scripts/init-wasm-canvas.js}}
+</script>
+{{#include ../../scripts/canvas.html}}
+
+## Overview
+
+* Objective: Self-assemble 3D capsules that are allowed to freely rotate while their
+  center is confined to a 2D plane.
+* File: `hoomd-rs/examples/mc-examples/capsules-on-a-plane.rs`
+* Run (interactively):
+  ```shell
+  cargo run --release --features "bevy" --example capsules-on-a-plane
+  ```
+* Run (in batch mode):
+  ```shell
+  cargo run --release --example capsules-on-a-plane
+  ```
+
+## Strategy
+
+1. Represent bodies with `Cartesian<2>` positions and `Versor` orientations.
+2. Define a custom `SiteProperties` with `Cartesian<3>` positions and `Versor`
+   orientations. Transform sites from the body frame to the simulation frame by first
+   lifting the body position into 3D: `(body_x, body_y, 0)` and then transforming
+   as normal.
+3. Define a custom `Boundary` type that wraps `Periodic<Rectangle>`.
+   Implement `Wrap<BodyProperties>`, `Volume`, `MapPoint`, `Scale`, and `Distribution`
+   for the custom boundary by calling the same methods on the inner type.
+   Implement `Wrap<SiteProperties>` and `GenerateGhosts` by projecting
+   the 3D site position into 2D, calling the same methods on the wrapped type,
+   then lift the result back into 3D.
+
+See the example code for details. It implements all of these steps in a general fashion.
+You can copy and paste this code and use it for Monte Carlo simulations with any 3D
+interaction model (including multi-site rigid bodies) where the body centers should
+be confined to the _xy_ plane.
+
+## Complete Code
+```rust,ignore
+{{#rustdoc_include ../../../examples/mc-examples/capsules-on-a-plane.rs:all}}

doc/src/release-notes.md

@@ -4,13 +4,18 @@
 
 *Added:*
 
+* `[examples]`: Add "Melt an ideal hexagonal structure of hexagons" example (#393).
+* `[examples]`: Add "Multi-site patchy shapes" example (#395).
+* `[examples]`: Add "3D shapes confined to a 2D plane" example (#397).
+* `[examples]`: Use the mouse wheel to zoom examples with 3D cameras (#397).
+* `[examples]`: Click and drag to orbit the camera in examples with 3D cameras (#397).
 * `[hoomd-geometry]`: Add `Hyperparallelepiped`, `Triclinic`, and `Rhomboid` shapes (#88).
 * `[hoomd-linear-algebra]` Add `matrix::qr` module with methods to compute the QR factorization of matrices (#88).
 * `[hoomd-linear-algebra]` Add methods `iter_column_slice`, `iter_column_slice_mut`, `iter_submatrix`, to `Matrix<N, M>` (#88).
 * `[hoomd-macrostate]`: Add `Fugacity` trait that access the fugacity of a macrostate (#354).
 * `[hoomd-macrostate]`: Add `IsothermoalIsofugacity` type that stores the system's temperature and fugacity (#354).
 * `[hoomd-mc]`: Add `GrandCanonical` trial move type. It inserts and removes bodies and samples from the constant chemical potential, constant volume, constant temperature ensemble (#354).
-* `[hoomd-mc`]: Add `InsertReMoveCount` type that counts the accepted and rejected insertion and removal moves (#354).
+* `[hoomd-mc`]: Add `InsertRemoveCount` type that counts the accepted and rejected insertion and removal moves (#354).
 * `[hoomd-microstate`]: Implement all traits necessary to use `Hyperparallelepiped`, `Triclinic`, and `Rhomboid` as simulation boundaries (#88).
 * `[hoomd-microstate`]: Implement `AppendMicrostate` for microstates with `Triclinic` and `Rhomboid` boundaries (#88).
 * `[hoomd-microstate`]: Add `Microstate::iter_bodies_tag_order` method that iterates over all bodies in tag order (#393).
@@ -19,23 +24,25 @@
 * `[hoomd-vector`]: Implement `Mul<Cartesian<N>> for f64`, `Mul<PositiveReal> for Cartesian<N>`, `Mul<Cartesian<N>> for PositiveReal`, `MulAssign<f64> for Cartesian<N>`, and `MulAssign<PositiveReal> for Cartesian<N>` (#88).
 * `[hoomd-vector`]: Add `Cartesian::basis` method that constructs Cartesian basis vectors (#393).
 * `[hoomd-workspace`]: Add the `hoomd-workspace` crate. Use it to initialize and read state points in a signac workspace (#359).
-* *examples*: Add "Melt an ideal hexagonal structure of hexagons" example (#393).
-* *examples*: Add "Multi-site patchy shapes" example (#395).
 
 *Changed:*
 
 * Build the documentation with mdBook 0.5.4 and KaTeX 0.18.1 (#376).
+* `[hoomd-microstate]`: Relax trait bounds to allow bodie and site positions to
+  have different types (#397).
+* `[hoomd-mc]`: Relax trait bounds to allow bodie and site positions to
+  have different types (#397).
 
 *Deprecated:*
 
 *Removed:*
 
 *Fixed:*
 
+* `[examples]`: Properly auto size egui parameter windows (#354).
+* `[examples]`: Reduce the zoom speed (#393).
 * `[hoomd-interaction]`: Fix typos in documentation (#358).
 * `[hoomd-microstate]`: Fix typos in documentation (#358).
-* *examples*: Properly auto size egui parameter windows (#354).
-* *examples*: Reduce the zoom speed (#393).
 
 ## 1.2.0 (2026-07-07)
 

examples/Cargo.toml

@@ -39,6 +39,7 @@ hoomd-spatial.workspace = true
 hoomd-utility.workspace = true
 hoomd-vector.workspace = true
 
+arrayvec.workspace = true
 anyhow.workspace = true
 bevy = { workspace = true, optional = true }
 bevy_egui = { workspace = true, optional = true }
@@ -169,3 +170,10 @@ path = "mc-examples/multi-site-patchy-shapes.rs"
 
 [package.metadata.example.multi-site-patchy-shapes]
 path = "mc-examples"
+
+[[example]]
+name = "capsules-on-a-plane"
+path = "mc-examples/capsules-on-a-plane.rs"
+
+[package.metadata.example.capsules-on-a-plane]
+path = "mc-examples"