Core (paos.core)

parseConfig

getfloat(value)[source]
parse_config(filename)[source]

Parse an ini lens file

Parameters:

filename (string) – full path to ini file

Returns:

  • pup_diameter (float) – pupil diameter in lens units

  • parameters (dict) – Dictionary with parameters defined in the section ‘general’ of the ini file

  • field (List) – list of fields

  • wavelengths (List) – list of wavelengths

  • opt_chain_list (List) – Each list entry is a dictionary of the optical surfaces in the .ini file, estimated at the given wavelength. (Relevant only for diffractive components)

Examples

>>> from paos.core.parseConfig import parse_config
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('path/to/ini/file')

coordinateBreak

coordinate_break(vt, vs, xdec, ydec, xrot, yrot, zrot, order=0)[source]

Performs a coordinate break and estimates the new \(\vec{v_{t}}=(y, u_{y})\) and \(\vec{v_{s}}=(x, u_{x})\).

Parameters:

  • vt (array) – vector \(\vec{v_{t}}=(y, u_{y})\) describing a ray propagating in the tangential plane

  • vs (array) – vector \(\vec{v_{s}}=(x, u_{x})\) describing a ray propagating in the sagittal plane

  • xdec (float) – x coordinate of the decenter to be applied

  • ydec (float) – y coordinate of the decenter to be applied

  • xrot (float) – tilt angle around the X axis to be applied

  • yrot (float) – tilt angle around the Y axis to be applied

  • zrot (float) – tilt angle around the Z axis to be applied

  • order (int) – order of the coordinate break, defaults to 0.

Returns:

two arrays representing the new \(\vec{v_{t}}=(y, u_{y})\) and \(\vec{v_{s}}=(x, u_{x})\).

Return type:

tuple

Note

When order=0, first a coordinate decenter is applied, followed by a XYZ rotation. Coordinate break orders other than 0 not implemented yet.

raytrace

raytrace(field, opt_chain, x=0.0, y=0.0)[source]

Diagnostic function that implements the Paraxial ray-tracing and prints the output for each surface of the optical chain as the ray positions and slopes in the tangential and sagittal planes.

Parameters:

  • field (dict) – contains the slopes in the tangential and sagittal planes as field={‘vt’: slopey, ‘vs’: slopex}

  • opt_chain (dict) – the dict of the optical elements returned by paos.parse_config

  • x (float) – X-coordinate of the initial ray position

  • y (float) – Y-coordinate of the initial ray position

Returns:

out – A list of strings where each list item is the raytrace at a given surface.

Return type:

list[str]

Examples

>>> from paos.core.parseConfig import parse_config
>>> from paos.core.raytrace import raytrace
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('path/to/conf/file')
>>> raytrace(fields[0], opt_chains[0])

run

push_results(wfo)[source]
run(pupil_diameter, wavelength, gridsize, zoom, field, opt_chain)[source]

Run the POP.

Parameters:

  • pupil_diameter (scalar) – input pupil diameter in meters

  • wavelength (scalar) – wavelength in meters

  • gridsize (scalar) – the size of the simulation grid. It has to be a power of 2

  • zoom (scalar) – zoom factor

  • field (dictionary) – contains the slopes in the tangential and sagittal planes as field={‘vt’: slopey, ‘vs’: slopex}

  • opt_chain (list) – the list of the optical elements parsed by paos.core.parseConfig.parse_config

Returns:

out – dictionary containing the results of the POP

Return type:

dict

Examples

>>> from paos.core.parseConfig import parse_config
>>> from paos.core.run import run
>>> from paos.core.plot import simple_plot
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('path/to/conf/file')
>>> ret_val = run(pup_diameter, 1.0e-6 * wavelengths[0], parameters['grid_size'], parameters['zoom'], fields[0], opt_chains[0])

plot

do_legend(axis, ncol=1)[source]

Create a nice legend for the plots

Parameters:

  • axis (Axes) – An instance of matplotlib axis

  • ncol (int) – The number of legend columns

Returns:

out – Produces a nice matplotlib legend

Return type:

None

simple_plot(fig, axis, key, item, ima_scale, origin='lower', cmap='viridis', options={})[source]

Given the POP simulation output dict, plots the squared amplitude of the wavefront at the given optical surface.

Parameters:

  • fig (Figure) – instance of matplotlib figure artist

  • axis (Axes) – instance of matplotlib axes artist

  • key (int) – optical surface index

  • item (dict) – optical surface dict

  • ima_scale (str) – plot color map scale, can be either ‘linear’ or ‘log’

  • origin (str) – matplotlib plot origin. Defaults to ‘lower’

  • cmap (str) – matplotlib plot color map. Defaults to ‘viridis’

  • options (dict) – dictionary containing the options to override the plotting default for one or more surfaces, specified by the dictionary key. Available options are the surface scale, an option to display physical units, the surface zoom(out), the plot scale and whether to plot dark rings in correspondance to the zeros of the Airy diffraction pattern. Examples: 0) options={4: {‘ima_scale’:’linear’}} 1) options={4: {‘surface_scale’:60, ‘ima_scale’:’linear’}} 2) options={4: {‘surface_scale’:21, ‘pixel_units’:True, ‘ima_scale’:’linear’}} 3) options={4: {‘surface_zoom’:2, ‘ima_scale’:’log’, ‘dark_rings’: False}}

Returns:

updates the Figure object

Return type:

None

Examples

>>> from paos.core.parseConfig import parse_config
>>> from paos.core.run import run
>>> from paos.core.plot import simple_plot
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('path/to/ini/file')
>>> ret_val = run(pup_diameter, 1.0e-6 * wavelengths[0], parameters['grid size'],
>>>              parameters['zoom'], fields[0], opt_chains[0])
>>> from matplotlib import pyplot as plt
>>> fig, ax = plt.subplots(nrows=1, ncols=1, figsize=(8, 8))
>>> key = list(ret_val.keys())[-1]  # plot at last optical surface
>>> item = ret_val[key]
>>> simple_plot(fig, ax, key=key, item=item, ima_scale='log')
>>> plt.show()
plot_pop(retval, ima_scale='log', ncols=2, figname=None, options={})[source]

Given the POP simulation output dict, plots the squared amplitude of the wavefront at all the optical surfaces.

Parameters:

  • retval (dict) – simulation output dictionary

  • ima_scale (str) – plot color map scale, can be either ‘linear’ or ‘log’

  • ncols (int) – number of columns for the subplots

  • figname (str) – name of figure to save

  • options (dict) – dict containing the options to display the plot: axis scale, axis unit, zoom scale and color scale. Examples: 0) options={4: {‘ima_scale’:’linear’}} 1) options={4: {‘surface_scale’:60, ‘ima_scale’:’linear’}} 2) options={4: {‘surface_scale’:21, ‘pixel_units’:True, ‘ima_scale’:’linear’}} 3) options={4: {‘surface_zoom’:2, ‘ima_scale’:’log’}}

Returns:

out – displays the plot output or stores it to the indicated plot path

Return type:

None

Examples

>>> from paos.core.parseConfig import parse_config
>>> from paos.core.run import run
>>> from paos.core.plot import plot_pop
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('path/to/ini/file')
>>> ret_val = run(pup_diameter, 1.0e-6 * wavelengths[0], parameters['grid size'],
>>>              parameters['zoom'], fields[0], opt_chains[0])
>>> plot_pop(ret_val, ima_scale='log', ncols=3, figname='path/to/output/plot')
plot_psf_xsec(fig, axis, key, item, ima_scale='linear', x_units='standard', surface_zoom=1)[source]

Given the POP simulation output dict, plots the cross-sections of the squared amplitude of the wavefront at the given optical surface.

Parameters:

  • fig (Figure) – instance of matplotlib figure artist

  • key (int) – optical surface index

  • item (dict) – optical surface dict

  • ima_scale (str) – y axis scale, can be either ‘linear’ or ‘log’

  • x_units (str) – units for x axis. Default is ‘standard’, to have units of mm or microns. Can also be ‘wave’, i.e. \(\textrm{Displacement} / (F_{num} \lambda)\).

  • surface_zoom (scalar) – Surface zoom: more increases the axis limits

Returns:

out – updates the ~matplotlib.figure.Figure object

Return type:

None

Examples

>>> import matplotlib.pyplot as plt
>>> from paos.core.parseConfig import parse_config
>>> from paos.core.run import run
>>> from paos.core.plot import plot_psf_xsec
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('/path/to/config/file')
>>> wl_idx = 0  # choose the first wavelength
>>> wavelength, opt_chain = wavelengths[wl_idx], opt_chains[wl_idx]
>>> ret_val = run(pup_diameter, 1.0e-6 * wavelength, parameters['grid_size'], parameters['zoom'],
>>>               fields[0], opt_chain)
>>> key = list(ret_val.keys())[-1]  # plot at last optical surface
>>> fig, ax = plt.subplots(nrows=1, ncols=1, figsize=(16, 8))
>>> plot_psf_xsec(fig=fig,axis=ax,key=key,item=ret_val[key],ima_scale='log',x_units='wave')
plot_surface(key, retval, ima_scale, origin='lower', zoom=1, figname=None)[source]

Given the optical surface key, the POP output dictionary and the image scale, plots the squared amplitude of the wavefront at the given surface (cross-sections and 2D plot)

Parameters:

  • key (int) – the key index associated to the optical surface

  • retval (dict) – the POP output dictionary

  • ima_scale (str) – the image scale. Can be either ‘linear’ or ‘log’

  • origin (str) – matplotlib plot origin. Defaults to ‘lower’

  • zoom (scalar) – the surface zoom factor: more increases the axis limits

  • figname (str) – name of figure to save

Returns:

out – the figure with the squared amplitude of the wavefront at the given surface

Return type:

Figure

saveOutput

remove_keys(dictionary, keys)[source]

Removes item at specified index from dictionary.

Parameters:

  • dictionary (dict) – input dictionary

  • keys – keys to remove from the input dictionary

Returns:

Updates the input dictionary by removing specific keys

Return type:

None

Examples

>>> from paos.core.saveOutput import remove_keys
>>> my_dict = {'a': 1, 'b': 2, 'c': 3, 'd': 4}
>>> print(my_dict)
>>> keys_to_drop = ['a', 'c', 'e']
>>> remove_keys(my_dict, keys_to_drop)
>>> print(my_dict)
save_recursively_to_hdf5(dictionary, outgroup)[source]

Given a dictionary and a hdf5 object, saves the dictionary to the hdf5 object.

Parameters:

  • dictionary (dict) – a dictionary instance to be stored in a hdf5 file

  • outgroup – a hdf5 file object in which to store the dictionary instance

Returns:

Save the dictionary recursively to the hdf5 output file

Return type:

None

save_info(file_name, out)[source]

Inspired by a similar function from ExoRad2. Given a hdf5 file name and a hdf5 file object, saves the information about the paos package to the hdf5 file object. This information includes the file name, the time of creation, the package creator names, the package name, the package version, the hdf5 package version and the h5py version.

Parameters:

  • file_name (str) – the hdf5 file name for saving the POP simulation

  • out – the hdf5 file object

Returns:

Saves the paos package information to the hdf5 output file

Return type:

None

save_retval(retval, keys_to_keep, out)[source]

Given the POP simulation output dictionary, the keys to store at each surface and the hdf5 file object, it saves the output dictionary to a hdf5 file.

Parameters:

  • retval (dict) – POP simulation output dictionary to be saved into hdf5 file

  • keys_to_keep (list) – dictionary keys to store at each surface. example: [‘amplitude’, ‘dx’, ‘dy’]

  • out (~h5py.File) – instance of hdf5 file object

Returns:

Saves the POP simulation output dictionary to the hdf5 output file

Return type:

None

save_output(retval, file_name, keys_to_keep=None, overwrite=True)[source]

Given the POP simulation output dictionary, a hdf5 file name and the keys to store at each surface, it saves the output dictionary along with the paos package information to the hdf5 output file. If indicated, overwrites past output file.

Parameters:

  • retval (dict) – POP simulation output dictionary to be saved into hdf5 file

  • file_name (str) – the hdf5 file name for saving the POP simulation

  • keys_to_keep (list) – dictionary keys to store at each surface. example: [‘amplitude’, ‘dx’, ‘dy’]

  • overwrite (bool) – if True, overwrites past output file

Returns:

Saves the POP simulation output dictionary along with the paos package information to the hdf5 output file

Return type:

None

Examples

>>> from paos.core.parseConfig import parse_config
>>> from paos.core.run import run
>>> from paos.core.saveOutput import save_output
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('path/to/ini/file')
>>> ret_val = run(pup_diameter, 1.0e-6 * wavelengths[0], parameters['grid size'],
>>>              parameters['zoom'], fields[0], opt_chains[0])
>>> save_output(ret_val, 'path/to/hdf5/file', keys_to_keep=['wfo', 'dx', 'dy'], overwrite=True)
save_datacube(retval_list, file_name, group_names, keys_to_keep=None, overwrite=True)[source]

Given a list of dictionaries with POP simulation output, a hdf5 file name, a list of identifiers to tag each simulation and the keys to store at each surface, it saves the outputs to a data cube along with the paos package information to the hdf5 output file. If indicated, overwrites past output file.

Parameters:

  • retval_list (list) – list of dictionaries with POP simulation outputs to be saved into a single hdf5 file

  • file_name (str) – the hdf5 file name for saving the POP simulation

  • group_names (list) – list of strings with unique identifiers for each POP simulation. example: for one optical chain run at different wavelengths, use each wavelength as identifier.

  • keys_to_keep (list) – dictionary keys to store at each surface. example: [‘amplitude’, ‘dx’, ‘dy]

  • overwrite (bool) – if True, overwrites past output file

Returns:

Saves a list of dictionaries with the POP simulation outputs to a single hdf5 file as a datacube with group tags (e.g. the wavelengths) to identify each simulation, along with the paos package information.

Return type:

None

Examples

>>> from paos.core.parseConfig import parse_config
>>> from paos.core.run import run
>>> from paos.core.saveOutput import save_datacube
>>> from joblib import Parallel, delayed
>>> from tqdm import tqdm
>>> pup_diameter, parameters, wavelengths, fields, opt_chains = parse_config('path/to/ini/file')
>>> ret_val_list = Parallel(n_jobs=2)(delayed(run)(pup_diameter, 1.0e-6 * wl, parameters['grid size'],
>>>               parameters['zoom'], fields[0], opt_chains[0]) for wl in tqdm(wavelengths))
>>> group_tags = list(map(str, wavelengths))
>>> save_datacube(ret_val_list, 'path/to/hdf5/file', group_tags,
>>>               keys_to_keep=['amplitude', 'dx', 'dy'], overwrite=True)

pipeline

pipeline(passvalue)[source]

Pipeline to run a POP simulation and save the results, given the input dictionary. This pipeline parses the lens file, performs a diagnostic ray tracing (optional), sets up the optical chain for the POP run automatizing the input of an aberration (optional), runs the POP in parallel or using a single thread and produces an output where all (or a subset) of the products are stored. If indicated, the output includes plots.

Parameters:

passvalue (dict) – input dictionary for the simulation

Returns:

If indicated, returns the simulation output dictionary or a list with a dictionary for each simulation. Otherwise, returns None.

Return type:

None or dict or list of dict

Examples

>>> from paos.core.pipeline import pipeline
>>> pipeline(passvalue={'conf':'path/to/conf/file',
>>>                     'output': 'path/to/output/file',
>>>                     'plot': True,
>>>                     'loglevel': 'debug',
>>>                     'n_jobs': 2,
>>>                     'store_keys': 'amplitude,dx,dy,wl',
>>>                     'return': False})