Pre v0.3.1: Critical fixes and internal changes that are functionality invariant

[crisbour]

This branch paves the way to the next release(v0.4.0), fixing critical issues and making changes that are desired, but which don't change the functionality of the model.

1. Critical changes:

• Scattering statistics: Output volume (measuring configuration) must not influence the model behvaiour, i.e. the scattering distance should be sampled only once and then progresively decremeanted as we are marching through the voxels/volume elements
• Surfaces should be allowed to coincide with boundary, hence the max boundary values must collapse to max index instead of resulting in out of bound index error
• If output volume coincide with surfaces, allow hit to be 0.0 distance

2. Code cleanup

• must_use can't be described in trait methods, and it's going to result in an error in next compiler release
• Trail whitespaces, elided lifetimes, hotfix MPI compile issue

3. Functionality invariant changes

• netcdf bump, I needed this to use the HDF5 library available on the stable nix flake + added nix flakes for env setup
• Use obj crate for wavefront parsing instead, in order to allow for more easily check of invalid format and useful semantics for next release
• aetherus::Error compatible with std::error::Error trait and autodecorate it with thiserror proc-macro crate
• Allow adding context to errors by extending it to wrap anyhow error
• Convert AttributeLinker endless immutable structure types that was hard to follow into a superposition struct of Value/Future inner values
• Allow Build trait to be failable

4. Functionality change:

• PhotonCollector only interact on one side, i.e. let the PhotonCollector be placed in the ray path for coaxial measurements, but only measure the reflected photons

TODO:

• Add CI/CD pipeline for compile and unit tests
• Add a CI/CD job for toolchain test in releases with the aetherus-test repo

[crisbour]

This is dependent on this PR on lidrs @sammorrell : sammorrell/lidrs#6

[crisbour]

To confirm you @sammorrell find that the changes are sensible:

• Part of the CRITICAL fixes was also a change I wasn't completely sure about, which is the assert for dist > 0, which I replaced to dist >= 0 as in one of the scenes I had, the boundary was overlapping with the surface of an object, hence hit dist can be 0. Hence the change to ignore this test: 4895666#diff-08135051335d5c7020f985178f9f3cc860da5a0165f9fa3e249ba6a4e68f8356R59
• Since bumping netcdf with used of ndarray feature, ended in a using 2 different ndarray versions incompatibly, so I bumped ndarray and rayon as well to get these 3 dependencies to be happy with one another
• Check aetherus-tests or previous runs for your experiment that this still produces the expected results

[sammorrell]

I have run the testing suite on this branch and the following test have failed because the related photon collector outputs are missing:

• test_attribute: out/attribute/photon_collector_{target9m}.csv
• test_shadows: out/propagation/photon_collector_{target1m}.csv
• test_specular_reflectance_asphalt_albedo: out/specular_reflection_albedo/photon_collector_{target}.csv
• test_specular_reflectance_uniform: out/specular_reflectance/photon_collector_{target}.csv

I've looked through the configuration and code. It's not entirely clear why these are consistently absent, but I will continue to investigate...

---

After a conversation with @crisbour today, the PhotonCollector structs now only collect photons from the 'front' of the geometry. The orientation of geometry in the test cases has been modified to remove this assumption -- all collector surfaces now face the direction of the incoming photons.

Fix implemented in: aetherus-wg/aetherus-tests@570b8a9

Now this is fixed, and all unit and integration tests are passing, I will check through the rest of the code.

[sammorrell]

Ran with the full city-scale simulation from our recent paper (https://doi.org/10.1098/rsif.2025.0453), and this produces a lux output consistent with the outputs from that paper. Differences are on the order of 1 -- 2% different for areas with good signal (e.g. streets). Will now do final checks and we can get this released.

[sammorrell]

@crisbour what would you like to do about this? Is this something we should consider fixing?

[crisbour]

@sammorrell This might be relevant to another fix I made about the ray Aabb(Cube) intersection. It seemed to fail in some scenarios, so I converted to trusted method: 096b874

[sammorrell]

Looks good. Most files are small style / tagging improvements, but the substantive changes look okay to me. Everything compiles, runs, passes unti tests, integration tests and has run a scientific test case (see thread for #69). Happy to merge this now.

Great work, @crisbour!