PR to track changes on the dev branch

[LouisDesdoigts]

v0.1.14

This version is a major upgrade to dLux across the board, increasing functionality, improving testing, docs enhancement, a back-end re-organisation, API changes to improve clarity and long-term stability, and an overall simplification of the code, classes and methods. These changes are in preparation for the submission to JOSS and following that, the 1.0 release.

Due to all of this, there have been a lot of changes, although migrating from v0.13.xx will be simple for end-users as the 'high-level' API is relatively unchanged beyond a few class name changes detailed below.

Changes

General

• All functions with a _to_ have been replaced with 2, ie rad_to_arcsec -> rad2arcsec. This falls more in line with the method signatures of jax/numpy and has been applied package wide.
• Python 3.9 is no longer supported. This is due to changes in an upstream package.
• Changed to a 'src/dLux' layout.

Layers

• All scripts containing layers have been moved into a sub-module layers, so it is clear which scripts are layer-specific (since they are a lot of them)
• All __call__ method have been renamed to apply. This is to prevent difficult to debug errors throws from optax when trying to optimise classes with a __call__ method.
• The calculate method of BasisLayer has been renamed to eval_basis.
• A series of similar DetectorLayers and OpticalLayers have been combined into UnifiedLayers, namely Rotate, Flip and Resize.
• Removed the IrregPolyAperture as it had some unresolved bugs. This is likely to be re-build in the new utils/geometry.py methods somewhere down the line.
• ApertureFactory has been removed in favor of the new utils.geometry module. A small tutorial on how to use this can be found in the 'How-To's/Building Apertures' section of the docs.

Sources

• The BinarySource object now has the attribute mean_flux, instead of just flux to improve clarity.

Utils

• Adds the 'array_ops.py' script, holding specific paraxial array-based operations
• pixel_coordinates -> nd_coords, improving clarity of the function names.
• All functionality from the apertures.py script has been raised into 'utils/cordinates.py', 'utils/geometry.py', 'utils/zernikes.py'
• All propagation functionality has been raised out of the Wavefront class and into the 'utils/propagation.py' script.
• A small amount of functionality from the Sources classes has been raised to the 'utils/sources.py' script.
• The methods in 'utils/optics.py' have been consolidated and simplified.

Wavefront

• Unified the FrenselWavefront and Wavefront classes. This comes with a namespace change to the propagation methods, detailed below.
  • All inverse options have been removed from the propagators, the direction is now decided by the current plane of the wavefront.
  • FFT -> propagate_FFT
  • MFT & shifted_MFT unified to -> propagate
  • fresnel_prop -> propagate_frensel

Optics -> OpticalSystems

• All xxxOptics classes have been renamed to xxxOpticalSystem, ie AngularOptics -> AngularOpticalSystem. This is to avoid confusion between the Optic layer class.
• Removed the LayeredOptics class, in favor of including a layers attribute in the (newly named) AngularOpticalSystem and CartesianOpticalSystem.
• As per the point above, the Angular and Cartesian Optical Systems have been reworked as child-classes of the LayeredOpticalSystem class. This means all OpticalSystem classes share wf_npixels, diameter and layers attribute, with the Cartesian and Angular versions have the extra psf_npixels, psf_pixel_scale and oversample attributes, still with their respective um and arcsecond pixel scale units.
• psf_oversample has been renamed to oversample and now also multiples the output number of pixels by the same value. As such oversample must now be an int, and a PSF with the correct npixels and pixel_scale can be achieved with the Downsample detector layer, or the utils/downsample method.
• Adds the insert_layer and remove_layer methods

Detectors

• Adds the insert_layer and remove_layer methods

Image -> PSF

• The Image class have been renamed to PSF
• The .psf attribute have been renamed to .data

Transformations

• Adds the CoordTransfrom class, allowing for coordinate transformations to be held in classes with a simplified API and structure, allowing for the Aperture classes to have much simpler pytree structure.

Instruments

• BaseInstrument has been re-named to Instrument
• The Instrument class has been re-named to Telescope
• Adds the Dither class, details in the 'Observation' section below

Observations

• Observations are fully removed. They were ultimately an extra layer of abstraction and complexity that was not needed. Users wishing to use this functionality should now just create a child-class of the Instrument or (new) Telescope class and then proceed as they would with the Observation class.

Docs

• The docs have been greatly re-worked an improved, much of this benefit comes from the back-end restructure of the package, and the raising of functionality from classes into the utils module
• All jupyter notebooks have been removed and replaced with automatically generated .md files as a way to reduce the overall size of the repo. This can be done locally using the docs/generate_mds.py file, run from the docs directory.
• UML diagrams and now automatically generated and populate the docs as a .png. This allows for users to easily understand how a class is created, and where all if its attributes and method are defined. This should allow for users to very easily navigate the code base and find the methods of all classes easily.
• The tutorials have been re-worked and greatly improved. We now have 'introductory' designed to get new users started, 'how-tos' that go through some of the key feautures and how to use them, and keeps the currently tutorials as under 'examples'. While the 'introductory' and 'how-tos' are not all completed, the core functionality and basic workflow is covered.