From f8ae96ef134d5bccc70fbab9f4b0c3495b22da4d Mon Sep 17 00:00:00 2001 From: Colin Date: Wed, 15 Jan 2025 01:47:14 +0000 Subject: [PATCH] README: clarify how to implement _compound_ materials --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index b5276d7..12778ff 100644 --- a/README.md +++ b/README.md @@ -227,6 +227,16 @@ to add a new material: - for `WgpuBackend` simulations: do the above and add a spirv entry-point specialized to your material. scroll to the bottom of [crates/spirv_backend/src/lib.rs](crates/spirv_backend/src/lib.rs) and follow the examples. +to use your new material alongside other materials like `IsomorphicConductor`, leverage the compound type wrappers +in [`compound.rs`](./crates/cross/src/mat/compound.rs): +`let my_sim = SpirvSim::, MyMat>>::new(...)` + +if the compound wrappers seem complicated, it's because they have to be in order to be compatible with SPIR-V, which +does not generally allow addresses to refer to more than one type. +hence something like `enum { A(IsomorphicConductor), B(MyMat) }` +has to instead be represented in memory like `(u8 /*discriminant*/, IsomorphicConductor, MyMat)`. +in practice, we do some extra tricks to fold the discriminant into the other fields and reduce memory usage. + as can be seen, the Material trait is fairly restrictive. its methods are immutable, and it doesn't even have access to the entire cell state (only the cell's M value, during `move_b_vec`). i'd be receptive to a PR or request that exposes more cell state or mutability: this is just an artifact of me tailoring this specifically to the class of materials i intended to use it for. ## What's in the Box