Improve regularisation documentation and add ADMT demo by jacklovell · Pull Request #427 · cherab/core

jacklovell · 2024-03-11T14:56:54Z

Add a Regularisation section to the tomography documentation, describing the functionality inside the admt_utils module.
Fixup the docstrings in admt_utils.
Add calculation of "skewed" second derivative operators, which operate along the diagonals of the grid.
Add a bolometer diagonstic system to Generomak.
Add a new example using the Generomak bolometers and the regularisation operators to perform isotropic and ADMT inversions.
Add a regularised NNLS function which uses sparse matrices.
Enable the functions in admt_utils to optionally output sparse matrices depending on the input.

* Add a Regularisation section to the tomography documentation, describing the functionality inside the admt_utils module. * Fixup the docstrings in admt_utils. * Add calculation of "skewed" second derivative operators, which operate along the diagonals of the grid. * Add a bolometer diagonstic system to Generomak. * Add a new example using the Generomak bolometers and the regularisation operators to perform isotropic and ADMT inversions.

vsnever

Thanks @jacklovell, very valuable demo. A similar regularisation is used in ITER divertor bolometry to reconstruct the radiation power density profile. Generomak also receives the first diagnostics, which in itself is great.

I think the changelog should reflect that this demo has been added, and also that the bolometric diagnostic model has been added to Generomak.

I also have some comments and a few suggestions.

* Fix the series of transforms to position and orient the bolometer cameras. * Update geometry parameters such that the lines of sight all follow a consistant convention and specify the channel ordering in the docstring. This required adding the ability to rotate the sensors about the viewing axis to reverse the channel order of the horizontal-poloidal camera. * Correct the docstring of load_bolometers to specify the correct number of 4-channel sensors in each camera. * Expand docstrings and comments to better describe the intricacies of setting up the bolometer geometry.

* More thorough commenting of the function to make it easier to follow what is going on and why. * Exploit the sparsity of the derivative opreators but using a dictionary-of-keys representation instead of dense numpy arrays. A dictionary is faster to insert single elements into inside the loop than a numpy array too. * Remove the `np.isnan` checkc which are slow for single elements, replace with a cheap check for `None`. * Support returning the operators as Scipy sparse arrays for use downstream. Default to returning as Numpy arrays for backwards compatibility. These changes result in an order of magnitude speedup in this function.

This is done automatically if the derivative operators are sparse. A dense operator is returned otherwise.

An alternative to `invert_regularised_nnls` using sparse weight and penalty matrices. The numerical algorithm used is slightly different to `scipy.optimize.nnls`, as it uses the TRF variant of a bounded `scipy.optimize.lsq_linear` with the lower bound set to 0 to enforce positivity. Since the results differ due to floating point precision, the sparse variant is implemented as a separate function to maintain backwards compatibility.

* Produce additional inversions which incorporate Generomak's tangentially-viewing channels, for comparison with the poloidal-only inversions. * Correctly scale the emissivity. * Fix removing the ray transfer grid from the world before forward-modelling the bolometer measurements. * Better explain why we're building the 1D <-> 2D maps by hand instead of just using the ray transfer matrix capabilities directly: this is for generality. * Use the sparse variant of the NNLS inversion for speed and memory efficiency. The grid is large enough for this to be worthwhile.

This makes it easier for users to explore the geometry and potentially even edit it for testing purposes.

This is a more common term in the literature for a bolometer unit integrating several (typically 4) channels.

* The 1D-to-2D and 2D-to-1D maps are the inverse of one another, so one can be computed from the other. Depending on how the end user forms their inversion grid it may be simpler to calculate the 1D-to-2D or the 2D-to-1D, so allow the caller to pass either and compute any missing mapping. If the caller already has both mappings (machine packages like cherab-jet, cherab-mastu and cherab-aug already generate both) then accept both too. * Add tests for auto-computing missing mappings. * Tests uncovered a bug converting the Dyy sparse operator to dense when `sparse=False` was passed: fix that and complete test coverage for `admt_utils`. * Simplify the ADMT script by only computing the 1D-to-2D map as this is fairly trivially obtained from the Ray Transfer object.

jacklovell · 2026-07-31T16:23:34Z

I've implemented the changes from both reviews now: thanks to @vsnever and @skuba31. I am going to hold firm on the formulism in generate_derivative_operators though, as I think the benefits of sparseness and explicitness outweigh any potential performance gains or loss of generality of the vectorized version Vlad proposed before the iterative improvements from the reviews. As a compromise the function is now better commented and the interface is a bit easier to use for callers as reflected in the demo.

Once this is approved I'll do a squash merge as the commit history is longer than necessary to keep going forwards.

skuba31

Nice work @jacklovell . I think that the documentation and code readability is significantly improved. The sparse support and ADMT demo are very useful additions. I have added a few minor comments for consideration before final approval.

Consisdently use (R, Z) coordinates in the poloidal plane

skuba31

I consider this PR to be ready for merge now.

jacklovell · 2024-03-11T14:56:54Z

Add a Regularisation section to the tomography documentation, describing the functionality inside the admt_utils module.
Fixup the docstrings in admt_utils.
Add calculation of "skewed" second derivative operators, which operate along the diagonals of the grid.
Add a bolometer diagonstic system to Generomak.
Add a new example using the Generomak bolometers and the regularisation operators to perform isotropic and ADMT inversions.
Add a regularised NNLS function which uses sparse matrices.
Enable the functions in admt_utils to optionally output sparse matrices depending on the input.

Fixes#382 and #380

* Add a Regularisation section to the tomography documentation, describing the functionality inside the admt_utils module. * Fixup the docstrings in admt_utils. * Add calculation of "skewed" second derivative operators, which operate along the diagonals of the grid. * Add a bolometer diagonstic system to Generomak. * Add a new example using the Generomak bolometers and the regularisation operators to perform isotropic and ADMT inversions.

vsnever