AgnosticOpticalElement¶

class hcipy.optics.AgnosticOpticalElement(grid_dependent=True, wavelength_dependent=True, max_in_cache=11)¶

Bases: hcipy.optics.optical_element.OpticalElement

Base class for optical elements that require additional processing/caching for supporting different grids or wavelengths.

This class is mant to simplify the creation of agnostic optical elements. When you have an optical element that explicitly needs an input grid and/or wavelength on initialization, you can use this class to simplify making it accept all input/output grids and/or wavelengths.

Instances are created by a function make_instance that derived classes should use to evaluate properties on the given input_grid, output_grid and wavelength. These properties are stored in an internal cache, and are reused for as long as they reside in the cache. Any function using forward or backward propagation will have access to the cached instance data. All caching and retrieving of cached data is made invisible to the user.

As instanced data can take a lot of memory, at most max_in_cache instances will be held in the cache at the time. If an additional instance is requested, the oldest instance will be thrown away, and the new instance will be put in the cache instead.

Parameters

grid_dependentboolean: If the instances should be separated by grid. Separate instances will be made if their grids change between invocations.
wavelength_dependentboolean: If the instances should be separated by grid.Separate instances will be made if wavelength changes between invocations.
max_in_cacheint: The maximum size of the internal cache for optical elements. Reduce this if the cache is using too much memory, increase if there are a lot of cache misses.

Methods Summary

`clear_cache`()	Clear the instance cache.
`construct_function`(function, args, *kwargs)	Construct a function based on the given function and arguments.
`evaluate_parameter`(parameter, input_grid, …)	Evaluate the parameter as function of (input_grid, output_grid, wavelength).
`get_input_grid`(output_grid, wavelength)	Calculate a best guess for the input grid given an output grid and wavelength.
`get_instance_data`(input_grid, output_grid, …)	Get the InstanceData object corresponding to the given grids and wavelength.
`get_output_grid`(input_grid, wavelength)	Calculate a best guess for the output grid given an input grid and wavelength.
`make_instance`(instance_data, input_grid, …)	Make an instance for this specific input_grid, output_grid, wavelength.

Methods Documentation

clear_cache()¶

Clear the instance cache.

This function should be called if agnostic data, that was used to create instance data, was changed by the user. Clearing the cache ensures that the propagations are always performed using up-to-date arguments.

construct_function(function, *args, **kwargs)¶

Construct a function based on the given function and arguments.

The arguments can be (input_grid, output_grid, wavelength) or any subset of this. The returned function has parameters which encompass all given parameters.

This function is especially usefull for creating properties that depend on parameters that depend on input_grid, output_grid and/or wavelength.

Parameters

functionfunction: The function on which to base the returned function.
*argsanything: The arguments for the given function.
**kwargsanything: The keyword arguments for the given function.

Returns

function: The constructed function.

Raises

RuntimeError: If the signature of one of the parameter is not recognized.

evaluate_parameter(parameter, input_grid, output_grid, wavelength)¶

Evaluate the parameter as function of (input_grid, output_grid, wavelength).

The parameter can be a function of all or a subset of these parameters. This function will try to guess the function signature and attempt evaluation of the given function.

Parameters

parameteranything: The parameter to evaluate.
input_gridGrid or None: The input grid.
output_gridGrid or None: The output grid.
wavelengthscalar or None: The wavelength.

Returns

any type: The evaluated parameter.

Raises

RuntimeError: If the function could not be evaluated using the best-guess signature.

get_input_grid(output_grid, wavelength)¶

Calculate a best guess for the input grid given an output grid and wavelength.

This function is intended to be implemented by a derived class.

Parameters

output_gridGrid: The output grid.
wavelengthscalar: The wavelength.

Returns

Grid: The best-guess input grid based on the given output grid and wavelength.

get_instance_data(input_grid, output_grid, wavelength)¶

Get the InstanceData object corresponding to the given grids and wavelength.

If no InstanceData can be found in the internal cache, a new instance will be constructed.

Parameters

input_gridGrid or None: The input grid.
output_gridGrid or None: The output grid.
wavelengthscalar or None: The wavelength.

get_output_grid(input_grid, wavelength)¶

Calculate a best guess for the output grid given an input grid and wavelength.

This function is intended to be implemented by a derived class.

Parameters

input_gridGrid: The input grid.
wavelengthscalar: The wavelength.

Returns

Grid: The best-guess output grid based on the given input grid and wavelength.

make_instance(instance_data, input_grid, output_grid, wavelength)¶

Make an instance for this specific input_grid, output_grid, wavelength.

This function is intended to be implemented by a derived class. Any properties evaluated for the instance can be stored into the instance_data object which is stored in the internal cache.

Parameters

instance_dataInstanceData: An object storing all data for this instance. This object can be modified this function.
input_gridGrid or None: The input grid.
output_gridGrid or None: The output grid.
wavelengthscalar or None: The wavelength.