dLux v0.14.0

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. If you have any troubles upgrading, please reach out via issues or email and I will be happy to help!

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.
• All layer-based inputs can now be passed in as a (key, layer) tuple in order to assign a user-specified key to the dictionary entry.
• 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 .image attribute has 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.

dLux v0.13.2

dLux v0.13.2

Package Wide

A small incremental release, primarily migrating the project from setup.py to pyproject.toml and adding pre-commit hooks for black autoformatting and ruff linting. These changes have been reflected in the README and CONTRIBUTING files.

New classes

• Flip

Flips the wavefront about an input axes

• Resize

Resizes the wavefront to npixels either via a pad or crop.

Namespace Changes:

• detector_layers.Rotate -> RotateDetector

This avoids the namespace clash with optical_layers.Rotate.

dLux v0.13.1

Major Update!

---

This update is a major overhaul of the backed of dLux in preparation of submission to JOSS, and the 1.0 release! This update expands the capabilities and flexibility of the software, all while removing around 5'000 line of code. Lets go through what these changes entail.

High Level

This update separates all of the classes from core.py into their own individual scripts, that means we now have quite a new scripts: optical_layers.py, instruments.py, images.py, detector_layers.py, along with some renamed scripts: optics.py -> optical_layers.py, detectors.py -> detector_layers.py, spectrums.py -> spectra.py.

The primary aim of these changes is to have a more clear and logical division of the different classes in order to make building your own dLux classes easier. The resulting package is split into a series of different types of classes, lets take a look at them:

Wavefronts and classes that modify them

There are three main types of classes: Wavefronts (wavefronts.py) which represent the state of some monochromatic wavefront. OpticalLayers perform transformations on Wavefronts and Optics (optics.py) classes which hold a series of OpticalLayers in order to model some optical system.

The OpticalLayers classes are split up into four different scripts:

• optical_layers.py Which contain basic optics classes allowing for the modification of the amplitude, opd and phase of wavefronts, plus titls, rotations etc.
• apertures.py Which contain classes that model apertures dynamically. It is very extensive and allows for the modelling of most apertures.
• aberrations.py Which contain classes that model aberrations dynamically.
• propagators.py Which contain classes that perform the propagation of the wavefront.

Images and classes that modify them

The dLux module also contains a series of classes that modify Images (images.py) which represent the state of some psf as it is transformed through a detector. The structure matches that of the Wavefront classes, with DetectorLayers (detector_layers.py) performing transformations on Images and Detectors (detectors.py) holding a series of DetectorLayers in order to model some detector.

Sources and Spectra

The dLux module also contains a series of classes that represent sources and their spectra. The Source classes (sources.py) represent some parametric source, while the Spectrum classes (spectra.py) represent the spectrum of the source.

Instruments and Observations

The Instrument (instruments.py) is designed to coherently model the interaction between these different components and the Observation (observations.py) classes allow for fine-grained control over the modelling of the Instrument class. An example of this is to allow for dithering patterns modeled, or for observing the same source using different instrumental filters.

Utils

This simply provides a series of useful functions that are used throughout the rest of the software.

---

Wavefronts

Now that we have that out of the way, lets take a look at the major changes. First and foremost is a re-think of how the Wavefronts classes should be interacted with. Previously, these were considered 'private' and generally shouldn't be interacted with by the user. Now this class has been re-worked and is now part of the 'public' API in order to allow users to create their own fast and efficient instrument-specific classes.

OpticalLayers

This has also facilitated and change in the way that OpticalLayers behave, made to be more flexible and general. While the Apertures, Aberrations and Propagators remain largely unchanged (beyond merging the classes into a smaller number of more flexible classes), the 'base' OpticalLayers are restructured into four primary classes: Optic, PhaseOptic, BasisOptic, PhaseBasisOptic. The Optic and PhaseOptic classes both hold an array of transmission values, a boolean normalise value, and either an opd or phase array. The BasisOptic and PhaseBasisOptic similarly have a transmission and normalise attribute, but instead of the opd or phase they have basis and coefficients. This allows for a set of basis vectors and coefficients to be specific that are generated dynamically at run time for things like optical aberrations.

Optics

The two above changes has facilitated a re-think in the way we specify optical system in dLux. Previously we had the single Optics class, which has now been re-named to LayeredOptics, which behaves similarly in that it takes in a list of layers, with the difference that we now no longer need to specify the npixels and diameter properties of the wavefront via the CreateWavefront layer (deprecated), as those two parameters are now properties of the LayeredOptics classes themselves.

There are also now three new classes that provide a simplified interface when working with basic single conjugate plane optical systems: AngularOptics, CartesianOptics and FlexibleOptics. Please refer to the updated docs for details on these classes.

Detectors, DetectorLayers and Images

All the classes that relate to the interaction with detectors have been re-worked to now have a symmetrical class structure to Optics, OpticalLayers and Wavefronts. However, the functionality is basically the same so we will not go into detail here.

Utils

The utils functions have been simplified, with some of the code being moved into external repos as they are not specific to dLux.

---

Building your own dLux class

dLux is designed to be a framework for differentiable optical modelling, in pursuit of this goal each class type now has a Base version, ie BaseOptics, BaseInstrument etc that can be used to create classes that will integrate seamlessly into the rest of the dLux framework. That means you create your own custom optics class that does whatever you want and all dLux sources, instruments etc will recognise and work with these classes! For details on this please refer to the API/Optics section of the docs.

---

These are the primary changes in this version, however there are lots of small back-end tweaks in terms of where bits of code live and how they interact with each other. I will not specify all of these changes here are most of them will not be relevant to users, and this merge is currently +10k -15k lines of code, so specificity each individual change is kind of beyond the pale at this point. This version can however be considered 'stable' as the package is now very flexible and modular and soon to be released as the 1.0 version!

dLux 0.12.0

Alright this is a fairly big one.

High level

Docs overhaul

The entire structure of the documentation has been changed. Docs pages are now build specifically from .md files giving a much finer-grained control over them, and reducing the overall number of files.

The backend of the docs is changed too, with the addition light/dark mode support.

A low-level tutorial has been added.

General usage sections now exist in the full API. There are still some sections that should be expanded upon, but the core stuff is covered.

A series of typos etc have been fixed.

API simplification

This stems from the desire to simplify a series of APIs across the package, primarily the core.model function. It now has two positional arguments, optics and sources. The sources input can either be a single Source object or a list/dict/tuple of Sources. It also no longer supports Filter input since this is not likely to be built for a while and no one can have been using it since it throws an NotImplementedError if you try to.

This has also led to a change in the core.xxx.model methods. They now don't support all of the core.model inputs, but rather only the inputs specific to that class. Check the new docs for details.

This also has led to the deprecation of Scene as it was primarily just a hidden class that was never interacted with and simply added class structure complexity without really bringing any benefit.

Together these changes have also simplified some of the tests - all round good.

optics.proapagte_multi -> optics.propagate

Enhancements

__getattr__ methods: Observation, Source

__getattr__ methods have been added to both the Observation and Source classes.

The same was added to the CompositeAperture class, just not in this specific PR. I mention this here for clarity in the changelog.

Note about parameter raising from sources: Since Scene is now deprecated, parameters from Source objects currently are not raised all the way to Instrument. A slightly more detailed __getattr__ method in Instrument needs to be built, though this is low-priority.

Deprecations

OpticalSystem

Scene

optics.CompoundAperture

Filter (techincally)

Tests

All updated to reflect these changes.

Issues

This PR should fix a large number of issues: #153 #188 #196 #197 #198 #200 #202 #205 #207 #208 #211 #215

dLux 0.11.1

Updates package to work with zodiax 0.3.0

dLux 0.11.0

Changes

The high level goal of this version is to remove all classes that are incompatible with the serialisation methods introduced in zodiax. This required removing all leaves that were functions ie observation and the zernike generating functions. Details of these changes are below.

---

Namespace changes

• SimpleAperture -> ApertureFactory 😉 @ataras2

---

New modules

aberrations.py

A new module designed to house the new aberrations classes Zernike, ZernikeBasis, AberrationsFactory. Zernike class is designed to generate a zernike polynomial dynamically. ZernikeBasis holds a list of individual Zernike classes and has extra methods to generate a full basis. AberrationsFactory is a simple interface to generate an ApplyBasisOPD class loaded with the appropriate pre-calculated basis. The apertures.py class has been updated to reflect these changes.

observations.py

A new module designed to hold observation classes. Implements an AbstractObservation class to be inherited from. Also implements Dither which allows for dithered observations. The Instrument class has been updated to take this new type of class and has had its dithering functionality removed. It similarly now searches for the observation class name in __getattr__ allowing for zodiax easy accessing.

---

Removed

• optics.CompoundAperture has been fully removed.

---

Docs

All changes are reflected in the docs.

---

Tests

• The new aberrations module remains tested by the AberratedAperture class tests, so no new tests have been added for this.
• Minor tests added for the Dither observation class and added to workflow

---

Other Changes

• All eqx.static_fields() calls removed (primarily on the names)
• utils.helpers.list_to_dict changed to update the name parameter of layers with namespace clashes
• AddBasisOPD.get_total_opd -> AddBasisOPD.get_opd

Full Changelog: v0.10.1...v0.11.0

dLux 0.10.1

Plane summaries (#201)

* Upgrading utils/coordinates to merge all pixel position functions into the single get_pixel_positions function

* Passing the order parameter though to the utils/interpolation.rotate function

* Passing order parameter through to map_coordinates in utils/interpolation.rotate

* Fixing optics.Rotate to take order parameter, update tests

* Removing old commented out code

* Building out the angular conversions in the utils/units.py script

* Adds the summary method to the ApplyBasisOPD

* Re-adds the CompundAperture class, to be removed later

* Small typo fix

* Adding summary methods to the apertures classes

* Adding summary methods to the propagator classes

* Adding general conversion methods to utils/units.py

* Adding display method to the optics classes

* Add the two_image_plot function to helpers

* Adding new methods to docs

* Updaing summary methods to use the new conversion methods

* Expanding the plot_two_images function

* Adds summary and plotting methods to OpticalLayer and Optics

* Adding the single_image_plot method

* Adding plotting and summary method to detectors, and core classes

* Fixing indexing in the rotate method to prevent dimension swapping

* Adding summary methods to the spectrums

* Updaing summary methods to print the layer name

* Adding summary methods to sources and spectrums

* Adding summarise method to Scene

* Updating Instrument.summarise to print Scene summary

* Small fix to CombinedSpectrum

* Adding spectrum_plot and docs for new helper methods

* Adding the rest of the summarise and plot methods

* Small bug fix to ApplyBasisCLIMB

* Removing old debug print statement

* Incrementing to 10.1, and setting tests to run on 3.11

dLux 0.10.0

Adds the new apertures module which implements a fully differentiable module allowing for the creation and optimisation of fully arbitrary apertures with aberrations.

dLux 0.9.2

Minor updates/bug fixes

Updates dLux to remove the base module and use the new package Zodiax

dLux 0.9.1

This is a very large update, preparing the package for the 1.0 release coming soon...