`dtmm.data`¶

Director and optical data creation and IO functions.

Conversion functions¶

director2data() generates optical data from director.
Q2data() generates optical data from the Q tensor.
director2order() computes order parameter from directo length.
director2Q() computes uniaxial Q tensor.
Q2director() computes an effective uniaxial director from a biaxial Q tensor.
director2angles() computes Euler rotation angles from the director.
angles2director() computes the director from Euler rotation angles.
Q2eps() converts Q tensor to epsilon tensor.
eps2epsva() converts epsilon tensor to epsilon eigenvalues and Euler angles.
epsva2eps() converts epsilon eigenvalues and Euler angles to epsilon tensor.
tensor2matrix() convert tensor to matrix.
matrix2tensor() convert matrix to tensor.
refind2eps() convert refractive index eigenvalues to epsilon eigenvalues.
uniaxial_order() creates uniaxial tensor from a biaxial eigenvalues.
eig_symmetry() creates effective tensor of given symmetry.
effective_data() computes effective (mean layers) 1D data from 3D data.

IO functions¶

read_director() reads 3D director data.
read_tensor() reads 3D tensor data.
read_raw() reads any raw data.
load_stack() loads optical data.
save_stack() saves optical data.

Data creation¶

nematic_droplet_data() builds sample data.
nematic_droplet_director() builds sample director.
cholesteric_droplet_data() builds sample data.
cholesteric_director() builds sample director.
expand() expands director data.
sphere_mask() builds a masking array.
rot90_director() rotates director by 90 degrees
rotate_director() rotates data by any angle

Module Contents¶

dtmm.data.read_director(file, shape, dtype=FDTYPE, sep='', endian=sys.byteorder, order='zyxn', nvec='xyz')¶

Reads raw director data from a binary or text file.

A convinient way to read director data from file.

Parameters

file (str or file) – Open file object or filename.
shape (sequence of ints) – Shape of the data array, e.g., (50, 24, 34, 3)
dtype (data-type) – Data type of the raw data. It is used to determine the size of the items in the file.
sep (str) – Separator between items if file is a text file. Empty (“”) separator means the file should be treated as binary. Spaces (” “) in the separator match zero or more whitespace characters. A separator consisting only of spaces must match at least one whitespace.
endian (str, optional) – Endianess of the data in file, e.g. ‘little’ or ‘big’. If endian is specified and it is different than sys.endian, data is byteswapped. By default no byteswapping is done.
order (str, optional) – Data order. It can be any permutation of ‘xyzn’. Defaults to ‘zyxn’. It describes what are the meaning of axes in data.
nvec (str, optional) – Order of the director data coordinates. Any permutation of ‘x’, ‘y’ and ‘z’, e.g. ‘yxz’, ‘zxy’ …

dtmm.data.read_tensor(file, shape, dtype=FDTYPE, sep='', endian=sys.byteorder, order='zyxn')¶

Reads raw tensor data from a binary or text file.

A convinient way to read tensor data from file.

Parameters

file (str or file) – Open file object or filename.
shape (sequence of ints) – Shape of the data array, e.g., (50, 24, 34, 6)
dtype (data-type) – Data type of the raw data. It is used to determine the size of the items in the file.
sep (str) – Separator between items if file is a text file. Empty (“”) separator means the file should be treated as binary. Spaces (” “) in the separator match zero or more whitespace characters. A separator consisting only of spaces must match at least one whitespace.
endian (str, optional) – Endianess of the data in file, e.g. ‘little’ or ‘big’. If endian is specified and it is different than sys.endian, data is byteswapped. By default no byteswapping is done.
order (str, optional) – Data order. It can be any permutation of ‘xyzn’. Defaults to ‘zyxn’. It describes what are the meaning of axes in data.

dtmm.data.rotate_director(rmat, data, method='linear', fill_value=(0.0, 0.0, 0.0), norm=True, out=None)¶

Rotate a director field around the center of the compute box by a specified rotation matrix. This rotation is lossy, as datapoints are interpolated. The shape of the output remains the same.

Parameters

rmat (array_like) – A 3x3 rotation matrix.
data (array_like) – Array specifying director field with ndim = 4
method (str) – Interpolation method “linear” or “nearest”
fill_value (numbers, optional) – If provided, the values (length 3 vector) to use for points outside of the interpolation domain. Defaults to (0.,0.,0.).
norm (bool,) – Whether to normalize the length of the director to 1. after rotation (interpolation) is performed. Because of interpolation error, the length of the director changes slightly, and this options adds a constant length constraint to reduce the error.
out (ndarray, optional) – Output array.

Returns

y – A rotated director field

Return type

ndarray

See also

data.rotate_director: a general rotation for arbitrary angle.

dtmm.data.director2data(director, mask=None, no=1.5, ne=1.6, nhost=None, scale_factor=1.0, thickness=None)¶

Builds optical data from director data. Director length is treated as an order parameter. Order parameter of S=1 means that refractive indices no and ne are set as the material parameters. With S!=1, a uniaxial_order() is used to calculate actual material parameters.

Parameters

director (ndarray) – A 4D array describing the director
mask (ndarray, optional) – If provided, this mask must be a 3D bolean mask that define voxels where nematic is present. This mask is used to define the nematic part of the sample. Volume not defined by the mask is treated as a host material. If mask is not provided, all data points are treated as a director.
no (float) – Ordinary refractive index
ne (float) – Extraordinary refractive index
nhost (float) – Host refracitve index (if mask is provided)
scale_factor (float) – The order parameter S obtained from the director length is scaled by this factor. Optical anisotropy is then epsa = S/scale_factor * (epse - epso).
thickness (ndarray) – Thickness of layers (in pixels). If not provided, this defaults to ones.

Returns

optical_data – A valid optical data tuple.

Return type

tuple

dtmm.data.Q2data(tensor, mask=None, no=1.5, ne=1.6, nhost=None, scale_factor=1.0, biaxial=False, thickness=None)¶

Builds optical data from Q tensor data.

Parameters

tensor ((..,6) or (..,3,3) array) – Q tensor with elements Q[0,0], Q[1,1], Q[2,2], Q[0,1], Q[0,2], Q[1,2]
mask (ndarray, optional) – If provided, this mask must be a 3D bolean mask that define voxels where nematic is present. This mask is used to define the nematic part of the sample. Volume not defined by the mask is treated as a host material. If mask is not provided, all data points are treated as a director.
no (float) – Ordinary refractive index (when biaxial = False)
ne (float) – Extraordinary refractive index (when biaxial = False)
nhost (float) – Host refracitve index (if mask is provided)
scale_factor (float) – The order parameter S obtained from the Q tensor is scaled by this factor. Optical anisotropy is then epsa = S/scale_factor *(epse - epso).
biaxial (bool) – Describes whether data is treated as biaxial or converted to uniaxial (default). If biaxial, no describes the mean value of n1 and n2 refractive indices eigenavalues and ne = n3.
thickness (ndarray, optional) – Thickness of layers (in pixels). If not provided, this defaults to ones.

Returns

optical_data – A valid optical data tuple.

Return type

tuple

dtmm.data.director2Q(director, order=1.0)¶

Computes Q tensor form the uniaxial director.

Parameters

director ((..,3) array) – Director vector. The length of the vector is the square of the order parameter.
order (float, optional) – In case director is normalized, this describes the order parameter.

Returns

Q – Q tensor with elements Q[0,0], Q[1,1], Q[2,2], Q[0,1], Q[0,2], Q[1,2]

Return type

(..,6) array

dtmm.data.Q2director(tensor, qlength=False)¶

Computes the director from tensor data

Parameters

tensor ((..,6) or (..,3,3) array) – Tensor data.
qlength (bool) – Specifies whether the length of the director is set to the S parameter or not. If not, director is scalled to unity length.

Returns

Q – Q tensor with elements Q[0,0], Q[1,1], Q[2,2], Q[0,1], Q[0,2], Q[1,2]

Return type

(..,6) array

dtmm.data.Q2eps(tensor, no=1.5, ne=1.6, scale_factor=1.0, out=None)¶

Converts Q tensor to epsilon tensor

Parameters

tensor ((..,6) or (..,3,3) ndarray) – A 4D array describing the Q tensor. If provided as a matrix, rhe elemnents are Q[0,0], Q[1,1], Q[2,2], Q[0,1], Q[0,2], Q[1,2]
no (float) – Ordinary refractive index
ne (float) – Extraordinary refractive index
scale_factor (float) – The order parameter S obtained from the Q tensor is scaled by this factor. Optical anisotropy is then epsa = S/scale_factor * (epse - epso).
out (ndarray, optional) – Output array

Returns

eps – Calculated epsilon tensor.

Return type

ndarray

dtmm.data.eps2epsva(eps)¶

Computes epsilon eigenvalues (epsv) and rotation angles (epsa) from epsilon tensor of shape (…,6) or represented as a (…,3,3)

Parameters: eps ((..,3,3) or (..,6) array) – Epsilon tensor. If provided as a (3,3) matrix, the elements are eps[0,0], eps[1,1], eps[2,2], eps[0,1], eps[0,2], eps[1,2]
Returns: epsv, epsa – Eigenvalues and Euler angles arrays.
Return type: ndarray, ndarray

dtmm.data.epsva2eps(epsv, epsa)¶

Computes epsilon from eigenvalues (epsv) and rotation angles (epsa)

Parameters

epsv ((..,3) array) – Epsilon eigenvalues array.
epsa ((..,3) array) – Euler angles array.

Returns

eps – Epsilon tensor arrays of shape (…,6). The elements are eps[0,0], eps[1,1], eps[2,2], eps[0,1], eps[0,2], eps[1,2]

Return type

ndarray

dtmm.data.validate_optical_data(data, homogeneous=False)¶

Validates optical data.

This function inspects validity of the optical data, and makes proper data conversions to match the optical data format. In case data is not valid and it cannot be converted to a valid data it raises an exception (ValueError).

Parameters

data (tuple of optical data) – A valid optical data tuple.
homogeneous (bool, optional) – Whether data is for a homogenous layer. (Inhomogeneous by defult)

Returns

data – Validated optical data tuple.

Return type

tuple

dtmm.data.raw2director(data, order='zyxn', nvec='xyz')¶

Converts raw data to director array.

Parameters

data (array) – Data array
order (str, optional) – Data order. It can be any permutation of ‘xyzn’. Defaults to ‘zyxn’. It describes what are the meaning of axes in data.
nvec (str, optional) – Order of the director data coordinates. Any permutation of ‘x’, ‘y’ and ‘z’, e.g. ‘yxz’, ‘zxy’. Defaults to ‘xyz’

Returns

director – A new array or same array (if no trasposing and data copying was made)

Return type

array

Example

>>> a = np.random.randn(10,11,12,3)
>>> director = raw2director(a, "xyzn")

dtmm.data.read_raw(file, shape, dtype, sep='', endian=sys.byteorder)¶

Reads raw data from a binary or text file.

Parameters

file (str or file) – Open file object or filename.
shape (sequence of ints) – Shape of the data array, e.g., (50, 24, 34, 3)
dtype (data-type) – Data type of the raw data. It is used to determine the size of the items in the file.
sep (str) – Separator between items if file is a text file. Empty (“”) separator means the file should be treated as binary. Spaces (” “) in the separator match zero or more whitespace characters. A separator consisting only of spaces must match at least one whitespace.
endian (str, optional) – Endianess of the data in file, e.g. ‘little’ or ‘big’. If endian is specified and it is different than sys.endian, data is byteswapped. By default no byteswapping is done.

dtmm.data.sphere_mask(shape, radius, offset=(0, 0, 0))¶

Returns a bool mask array that defines a sphere.

The resulting bool array will have ones (True) insede the sphere and zeros (False) outside of the sphere that is centered in the compute box center.

Parameters

shape ((int,int,int)) – A tuple of (nlayers, height, width) defining the bounding box of the sphere.
radius (int) – Radius of the sphere in pixels.
offset ((int, int, int), optional) – Offset of the sphere from the center of the bounding box. The coordinates are (x,y,z).

Returns

out – Bool array defining the sphere.

Return type

array

dtmm.data.nematic_droplet_director(shape, radius, profile='r', retmask=False)¶

Returns nematic director data of a nematic droplet with a given radius.

Parameters

shape (tuple) – (nz,nx,ny) shape of the output data box. First dimension is the number of layers, second and third are the x and y dimensions of the box.
radius (float) – radius of the droplet.
profile (str, optional) – Director profile type. It can be a radial profile “r”, or homeotropic profile with director orientation specified with the parameter “x”, “y”, or “z”, or as a director tuple e.g. (np.sin(0.2),0,np.cos(0.2)). Note that director length defines order parameter (S=1 for this example).
retmask (bool, optional) – Whether to output mask data as well

Returns

out – A director data array, or tuple of director mask and director data arrays.

Return type

array or tuple of arrays

dtmm.data.cholesteric_director(shape, pitch, hand='left')¶

Returns a cholesteric director data.

Parameters

shape (tuple) – (nz,nx,ny) shape of the output data box. First dimension is the number of layers, second and third are the x and y dimensions of the box.
pitch (float) – Cholesteric pitch in pixel units.
hand (str, optional) – Handedness of the pitch; either ‘left’ (default) or ‘right’

Returns

out – A director data array

Return type

ndarray

dtmm.data.nematic_droplet_data(shape, radius, profile='r', no=1.5, ne=1.6, nhost=1.5)¶

Returns nematic droplet optical_data.

This function returns a thickness, material_eps, angles, info tuple of a nematic droplet, suitable for light propagation calculation tests.

Parameters

shape (tuple) – (nz,nx,ny) shape of the stack. First dimension is the number of layers, second and third are the x and y dimensions of the compute box.
radius (float) – radius of the droplet.
profile (str, optional) – Director profile type. It can be a radial profile “r”, or homeotropic profile with director orientation specified with the parameter “x”, “y”, or “z”.
no (float, optional) – Ordinary refractive index of the material (1.5 by default)
ne (float, optional) – Extraordinary refractive index (1.6 by default)
nhost (float, optional) – Host material refractive index (1.5 by default)

Returns

out – A (thickness, material_eps, angles) tuple of three arrays

Return type

tuple of length 3

dtmm.data.cholesteric_droplet_data(shape, radius, pitch, hand='left', no=1.5, ne=1.6, nhost=1.5)¶

Returns cholesteric droplet optical_data.

This function returns a thickness, material_eps, angles, info tuple of a cholesteric droplet, suitable for light propagation calculation tests.

Parameters

shape (tuple) – (nz,nx,ny) shape of the stack. First dimension is the number of layers, second and third are the x and y dimensions of the compute box.
radius (float) – radius of the droplet.
pitch (float) – Cholesteric pitch in pixel units.
hand (str, optional) – Handedness of the pitch; either ‘left’ (default) or ‘right’
no (float, optional) – Ordinary refractive index of the material (1.5 by default)
ne (float, optional) – Extraordinary refractive index (1.6 by default)
nhost (float, optional) – Host material refractive index (1.5 by default)

Returns

out – A (thickness, material_eps, angles) tuple of three arrays

Return type

tuple of length 3

dtmm.data.director2order(data, out)¶: Converts director data to order parameter (square root of the length of the director)

dtmm.data.director2angles(data, out)¶: Converts director data to angles (yaw, theta phi)

dtmm.data.angles2director(data, out)¶: Converts angles data (yaw,theta,phi) to director (nx,ny,nz)

dtmm.data.expand(data, shape, xoff=None, yoff=None, zoff=None, fill_value=0.0)¶

Creates a new scalar or vector field data with an expanded volume. Missing data points are filled with fill_value. Output data shape must be larger than the original data.

Parameters

data (array_like) – Input vector or scalar field data
shape (array_like) – A scalar or length 3 vector that defines the volume of the output data
xoff (int, optional) – Data offset value in the x direction. If provided, original data is copied to new data starting at this offset value. If not provided, data is copied symmetrically (default).
yoff – Data offset value in the x direction.
int – Data offset value in the x direction.
optional – Data offset value in the x direction.
zoff – Data offset value in the z direction.
int – Data offset value in the z direction.
optional – Data offset value in the z direction.
fill_value (array_like) – A length 3 vector of default values for the border volume data points.

Returns

y – Expanded ouput data

Return type

array_like

dtmm.data.refind2eps(refind)¶: Converts refractive index to epsilon

dtmm.data.uniaxial_order(order, eig, out)¶

uniaxial_order(order, eps)

Calculates uniaxial (or isotropic) eigen tensor from a diagonal biaxial eigen tensor.

Parameters

order (float) – The order parameter. 1.: uniaxial, 0.: isotropic. If order is negative no change is made (biaxial case).
eig (array) – Array of shape (…,3), the eigenvalues. The eigenvalue [2] is treated as the extraordinary axis for the uniaxial order.
out (ndarray) – Output array.
out – Effective eigenvalues based on the provided symmetry (order) argument
np.allclose(uniaxial_order(0 (>>>) –
[1 –
2 –
3.]) –
(2 –
2 –
2)) –
True –
uniaxial_order(1 (>>>) –
[1 –
2 –
3.] –
(1.5 –
1.5 –
3)) –
True –
uniaxial_order(-1 (>>>) –
[1 –
2 –
3.] –
(1 –
2 –
#negative (3))) –
no change (so) –
True –
np.allclose(uniaxial_order(0.5 (>>>) –
[1 –
2 –
3.]) –
(1.75 –
1.75 –
#scale accordingly (2.5))) –
True –

dtmm.data.eig_symmetry(order, eig, out=None)¶

Takes the ordered diagonal values of the tensor and converts it to uniaxial or isotropic tensor, or keeps it as biaxial.

Broadcasting rules apply.

Parameters

order (int or array) – Integer describing the symmetry 0 : isotropic, 1 : uniaxial, 2 : biaxial. If specified as an array it mast be broadcastable. See uniaxial_order().
eig (array) – Array of shape (…,3), the eigenvalues. The eigenvalue [2] is treated as the extraordinary axis for the uniaxial order.
out (ndarray) – Output array.
out – Effective eigenvalues based on the provided symmetry (order) argument

dtmm.data¶

Conversion functions¶

IO functions¶

Data creation¶

Module Contents¶

`dtmm.data`¶