holopy.core package

Module contents

Loading, saving, and basic processing of data.

holopy.core contains code to load images and holopy yamls into marray objects. It also contains the machinery for saving all HoloPy objects as holopy yaml files. Finally, it provides some basic mathematical operations, mostly as higher level wrappers around numpy or scipy routines.

Main use cases are

  1. Image or other data file + metadata => Image or other Marray object
  2. Raw Image + processing => processed Image object
  3. Any HoloPyObject from calculations or processing => achival yaml text or text/binary result

holopy.core.holopy_object module

Root class for all of holopy. This class provides serialization to and from yaml text file for all holopy objects.

yaml files are structured text files designed to be easy for humans to read and write but also easy for computers to read. HoloPy uses them to store information about experimental conditions and to describe analysis procedures.

class HoloPyObject

Bases: holopy.core.holopy_object.Serializable

Ancestor class for all HoloPy classes.

HoloPy object’s purpose is to provide the machinery for saving to and loading from HoloPy yaml files

classmethod from_yaml(loader, node)
like_me(filter_none=True, **kwargs)
classmethod to_yaml(dumper, data)
class Serializable

Bases: yaml.YAMLObject

Base class for any object that wants a nice clean yaml output

classmethod to_yaml(dumper, data)
class SerializableMetaclass(name, bases, kwds)

Bases: yaml.YAMLObjectMetaclass

ordered_dump(dumper, tag, data)

holopy.core.math module

cartesian_distance(p1, p2=[0, 0, 0])

Return the Cartesian distance between points p1 and p2.

Parameters:p2 (p1,) – Coordinates of point 1 and point 2 in N-dimensions
Returns:dist – Cartesian distance between points p1 and p2
Return type:float64
chisq(fit, data)

Calculate per-point value of chi-squared comparing a best-fit model and data.

  • fit (array_like) – Values of best-fit model to be compared to data
  • data (array_like) – Data values to be compared to model

chisq – Chi-squared per point

Return type:



chi-squared is defined as

\[\chi^2 = \frac{1}{N}\sum_{\textrm{points}} (\textrm{fit} - \textrm{data})^2\]

where \(N\) is the number of data points.

rotate_points(points, theta, phi, psi)

Rotate an array of points about Euler angles in a z, y, z convention.

  • points (array-like (n,3)) – Set of points to be rotated
  • phi, psi (theta,) – Euler rotation angles in z, y, z convention. These are not the same as angles in spherical coordinates.

rotated_points – Points rotated by Euler angles

Return type:


rotation_matrix(alpha, beta, gamma, radians=True)

Return a 3D rotation matrix

  • beta, gamma (alpha,) – Euler rotation angles in z, y, z convention
  • radians (boolean) – Default True; treats input angles in radians

rot – Rotation matrix. To rotate a column vector x, use np.dot(rot, x.)

Return type:



The Euler angles rotate a vector (in the active picture) by alpha clockwise about the fixed lab z axis, beta clockwise about the lab y axis, and by gamma about the lab z axis. Clockwise is defined as viewed from the origin, looking in the positive direction along an axis.

This breaks compatability with previous conventions, which were adopted for compatability with the passive picture used by SCSMFO.

rsq(fit, data)

Calculate correlation coeffiction R-squared comparing a best-fit model and data.

  • fit (array_like) – Values of best-fit model to be compared to data
  • data (array_like) – Data values to be compared to model

rsq – Correlation coefficient R-squared.

Return type:



R-squared is defined as

\[R^2 = 1 - \frac{\sum_{\textrm{points}} (\textrm{data} - \textrm{fit})^2}{\sum_{\textrm{points}} (\textrm{data} - \bar{\textrm{data}})^2}\]

where \(\bar{\textrm{data}}\) is the mean value of the data. If the model perfectly describes the data, \(R^2 = 1\).

to_cartesian(r, theta, phi)

Returns Cartesian coordinates of a point given in spherical polar coordinates.

Parameters:theta, phi (r,) – Spherical polar coordinates of point.
Returns:cartesian_coords – Dictionary of Cartesian coordinates of point with keys ‘x’, ‘y’, and ‘z’.
Return type:dict
to_spherical(x, y, z)

Return the spherical polar coordinates of a point in Cartesian coordinates.

Parameters:y, z (x,) – Cartesian coordinates of point
Returns:spherical_coords – Dictionary of spherical polar coordinates (r, theta, phi) of point with keys ‘r’, ‘theta’, ‘phi’.
Return type:dict


theta is the polar angle measured from the z axis with range (0, pi). phi is the azimuthal angle with range (0, 2 pi).

holopy.core.metadata module

Classes for defining metadata about experimental or calculated results.

copy_metadata(old, new, do_coords=True)
data_grid(arr, spacing=None, medium_index=None, illum_wavelen=None, illum_polarization=None, normals=None, name=None, z=0)

Create a set of detector points along with other experimental metadata.

Return type:DataArray object


Use of higher-level detector_grid() and detector_points() functions is recommended.

default_norms(coords, n)
detector_grid(shape, spacing, normals=None, name=None)

Create a rectangular grid of pixels to represent a detector on which scattering calculations are to be performed.

  • shape (int or list-like (2)) – If int, detector is a square grid of shape x shape points. If array_like, detector has shape[0] rows and shape[1] columns.
  • spacing (int or list-like (2)) – If int, distance between square detector pixels. If array_like, spacing[0] between adjacent rows and spacing[1] between adjacent columns.
  • normals (list-like or None) – If list-like, detector orientation.
  • name (string) –

grid – DataArray of zeros with coordinates calculated according to shape and spacing

Return type:

DataArray object


Typically used to define a set of points to represent the pixels of a digital camera in scattering calculations.

detector_points(coords={}, x=None, y=None, z=None, r=None, theta=None, phi=None, normals='auto', name=None)

Returns a one-dimensional set of detector coordinates at which scattering calculations are to be done.

  • coords (dict, optional) – Dictionary of detector coordinates. Default: empty dictionary. Typical usage should not pass this argument, giving other parameters (Cartesian x, y, and z or polar r, theta, and phi coordinates) instead.
  • y (x,) – Cartesian x and y coordinates of detectors.
  • z (int or array_like, optional) – Cartesian z coordinates of detectors. If not specified, assume z = 0.
  • r (int or array_like, optional) – Spherical polar radial coordinates of detectors. If not specified, assume r = infinity (far-field).
  • theta (int or array_like, optional) – Spherical polar coordinates (polar angle from z axis) of detectors.
  • phi (int or array_like, optional) – Spherical polar azimuthal coodinates of detectors.
  • normals (string, optional) – Default behavior: normal in +z direction for Cartesian coordinates, -r direction for polar coordinates. Non-default behavior not currently implemented.
  • name (string) –

grid – DataArray of zeros with calculated coordinates.

Return type:

DataArray object


Specify either the Cartesian or the polar coordinates of your detector. This may be helpful for modeling static light scattering calculations. Use detector_grid() to specify coordinates of a grid of pixels (e.g., a digital camera.)

make_coords(shape, spacing, z=0)
sphere_coords(a, origin=(0, 0, 0), wavevec=1)
update_metadata(a, medium_index=None, illum_wavelen=None, illum_polarization=None, normals=None)

Returns a copy of an image with updated metadata in its ‘attrs’ field.

  • a (xarray.DataArray) – image to update.
  • medium_index (float) – Updated refractive index of the medium in the image.
  • illum_wavelen (float) – Updated wavelength of illumination in the image.
  • illum_polarization (list-like) – Updated polarization of illumination in the image.
  • normals (list-like) – Updated detector orientation of the image.

b – copy of input image with updated metadata. The ‘normals’ field is not allowed to be empty.

Return type:


holopy.core.utils module

Misc utility functions to make coding more convenient

dict_without(d, keys)

Exclude a list of keys from a dictionary.

Silently ignores any key in keys that is not in the dict (this is intended to be used to make sure a dict does not contain specific keys) :param d: The dictionary to operate on :type d: dict :param keys: The keys to exclude :type keys: list(string) :param returns: A copy of dict without any of the specified keys :type returns: d2


Check if something is None.

This can’t be done with a simple is check anymore because numpy decided that array is None should do an element wise comparison.

Parameters:o (object) – Anything you want to see if is None

Equivalent to mkdir -p at the shell, this function makes a directory and its parents as needed, silently doing nothing if it exists.

repeat_sing_dims(indict, keys='all')
updated(d, update={}, filter_none=True, **kwargs)

Return a dictionary updated with keys from update

Analgous to sorted, this is an equivalent of d.update as a non-modifying free function

  • d (dict) – The dict to update
  • update (dict) – The dict to take updates from