6.6. tracer.geometry.surface Submodule¶

6.6.1. tracer.geometry.surface.aspheric_surface¶

class optrace.tracer.geometry.surface.aspheric_surface.AsphericSurface(r, R, k, coeff, **kwargs)¶

Define an aspheric surface, which is a ConicSurface with a n additional polynomial component a_0*r^2 + a_1*r^4 + … There is no upper bound on number of coefficients

Parameters:

r (float) – surface radius
R (float) – curvature circle
k (float) – conic constant
coeff (list | ndarray) – coefficients for orders r^2, r^4, r^6, … as list, where units are mm^-1, mm^-3, …
kwargs – additional keyword arguments for parent classes

flip()¶

flip the surface around the x-axis

Return type:: None

property info: str¶: info string, characterizing the surface

rotational_symmetry: bool = True¶: has the surface rotation symmetry?

6.6.2. tracer.geometry.surface.circular_surface¶

class optrace.tracer.geometry.surface.circular_surface.CircularSurface(r, **kwargs)¶

Create a surface object. The z-coordinate in the pos array is irrelevant if the surface is used for a lens, since it wil be adapted inside the lens class

Parameters:

r (float) – radial size for surface_type=”Conic”, “Sphere”, “Circle” or “Ring” (float)
kwargs – additional keyword arguments for parent classes

random_positions(N)¶

Get 3D random positions on the surface, uniformly distributed.

Parameters:: N (int) – number of positions
Returns:: position array, shape (N, 3)
Return type:: ndarray

rotational_symmetry: bool = True¶: has the surface rotational symmetry? Needs to be overwritten by child classes

6.6.3. tracer.geometry.surface.conic_surface¶

class optrace.tracer.geometry.surface.conic_surface.ConicSurface(r, R, k, **kwargs)¶

Define a conic section surface, following the equation: z(r) = 1/R * r**2 / (1 + sqrt(1 - (k+1) * r**2 / R**2))

Parameters:

R (float) – curvature circle for surface_type=”Conic” or “Sphere” (float)
r (float) – radial size for surface_type=”Conic”, “Sphere”, “Circle” or “Ring” (float)
k (float) – conic constant for surface_type=”Conic” (float)
kwargs – additional keyword arguments for parent classes

find_hit(p, s)¶

Find hit/intersections of rays with this surface.

Parameters:

p (ndarray) – ray position array, shape (N, 3)
s (ndarray) – unity ray direction vectors, shape (N, 3)

Returns:

intersection position (shape (N, 3)), boolean array (shape N) declaring a hit, indices of ill-conditioned rays

Return type:

tuple[ndarray, ndarray, ndarray]

flip()¶

flip the surface around the x-axis

Return type:: None

normals(x, y)¶

Get normal vectors of the surface.

Parameters:

x (ndarray) – x-coordinates (numpy 1D array)
y (ndarray) – y-coordinates (numpy 1D array)

Returns:

normal vector array of shape (x.shape[0], 3), components in second dimension (numpy 2D array)

Return type:

ndarray

property info: str¶: property string for UI information

rotational_symmetry: bool = True¶: has the surface rotational symmetry?

6.6.4. tracer.geometry.surface.data_surface_1d¶

class optrace.tracer.geometry.surface.data_surface_1d.DataSurface1D(r, data, parax_roc=None, **kwargs)¶

Define a data surface with rotational symmetry.

Parameters:

r (float) – surface radius
parax_roc (float) – paraxial radius of curvature, optional
data (ndarray) – equi-spaced data array, going from 0 to r
kwargs – additional keyword arguments for parent classes

rotational_symmetry: bool = True¶: has the surface rotational symmetry?

6.6.5. tracer.geometry.surface.data_surface_2d¶

class optrace.tracer.geometry.surface.data_surface_2d.DataSurface2D(r, data, parax_roc=None, **kwargs)¶

Create a surface object, defined by a two dimensional data set.

Parameters:

r (float) – radial size of surface
parax_roc (float) – paraxial radius of curvature, optional
data (ndarray) – uses copy of this array, grid z-coordinate array for surface_type=”Data” (numpy 2D array)
kwargs – additional keyword arguments for parent classes

flip()¶

flip the surface around the x-axis

Return type:: None

normals(x, y)¶

Get normal vectors of the surface.

Parameters:

x (ndarray) – x-coordinates (numpy 1D array)
y (ndarray) – y-coordinates (numpy 1D array)

Returns:

normal vector array of shape (x.shape[0], 3), components in second dimension (numpy 2D array)

Return type:

ndarray

rotate(angle)¶

rotate the surface around the z-axis

Parameters:: angle (float) – rotation angle in degrees
Return type:: None

rotational_symmetry: bool = False¶: has the surface rotational symmetry?

6.6.6. tracer.geometry.surface.function_surface_1d¶

class optrace.tracer.geometry.surface.function_surface_1d.FunctionSurface1D(r, func, mask_func=None, deriv_func=None, func_args={}, mask_args={}, deriv_args={}, z_min=None, z_max=None, parax_roc=None, **kwargs)¶

Create a surface object defined by a mathematical function.

Most of the time the automatic detection of the surface extent values z_min, z_max works correctly, assign the values manually otherwise.

Providing parax_roc only makes sense, if the surface center can be locally described by a spherical surface.

Parameters:

r (float) – surface radius
func (Callable[[ndarray], ndarray]) – surface function, must take one 1D array (r positions) and return one 1D float array
mask_func (Callable[[ndarray], ndarray]) – mask function (optional), must take one 1D array (r positions) and return one boolean 1D array, where the surface is defined
deriv_func (Callable[[ndarray], ndarray]) – derivative function (optional), must take one 1D array (r positions) and return one float 1D array with the derivative in r-direction
func_args (dict) – optional dict for keyword arguments for parameter func
mask_args (dict) – optional dict for keyword arguments for parameter mask_func
deriv_args (dict) – optional dict for keyword arguments for parameter deriv_func
parax_roc (float) – optional paraxial radius of curvature
z_min (float) – exact value for the maximum surface z-extent, optional
z_max (float) – exact value for the minimum surface z-extent, optional
kwargs – additional keyword arguments for parent classes

rotational_symmetry: bool = True¶: has the surface rotational symmetry?

6.6.7. tracer.geometry.surface.function_surface_2d¶

class optrace.tracer.geometry.surface.function_surface_2d.FunctionSurface2D(r, func, mask_func=None, deriv_func=None, func_args={}, mask_args={}, deriv_args={}, z_min=None, z_max=None, parax_roc=None, **kwargs)¶

Create a surface object defined by a mathematical function.

Most of the time the automatic detection of the surface extent values z_min, z_max works correctly, assign the values manually otherwise.

Providing parax_roc only makes sense, if the surface center can be locally described by a spherical surface.

Parameters:

r (float) – surface radius
func (Callable[[ndarray, ndarray], ndarray]) – surface function, must take two 1D arrays (x and y positions) and return one 1D float array
mask_func (Callable[[ndarray, ndarray], ndarray]) – mask function (optional), must take two 1D arrays (x and y positions) and return one boolean 1D array, where the surface is defined
deriv_func (Callable[[ndarray, ndarray], tuple[ndarray, ndarray]]) – derivative function (optional), must take two 1D arrays (x and y positions) and return two float 1D arrays with partial derivatives in x and y direction
func_args (dict) – optional dict for keyword arguments for parameter func
mask_args (dict) – optional dict for keyword arguments for parameter mask_func
deriv_args (dict) – optional dict for keyword arguments for parameter deriv_func
parax_roc (float) – optional paraxial radius of curvature
z_min (float) – exact value for the maximum surface z-extent, optional
z_max (float) – exact value for the minimum surface z-extent, optional
kwargs – additional keyword arguments for parent classes

flip()¶

flip the surface around the x-axis

Return type:: None

mask(x, y)¶

Get surface mask values. A value of 1 means the surface is defined here.

Parameters:

x (ndarray) – x-coordinate array (numpy 1D or 2D array)
y (ndarray) – y-coordinate array (numpy 1D or 2D array)

Returns:

z-coordinate array (numpy 1D or 2D array, depending on shape of x and y)

Return type:

ndarray

normals(x, y)¶

Get normal vectors of the surface.

Parameters:

x (ndarray) – x-coordinates (numpy 1D array)
y (ndarray) – y-coordinates (numpy 1D array)

Returns:

normal vector array of shape (x.shape[0], 3), components in second dimension (numpy 2D array)

Return type:

ndarray

rotate(angle)¶

rotate the surface around the z-axis

Parameters:: angle (float) – rotation angle in degrees
Return type:: None

rotational_symmetry: bool = False¶: has the surface rotational symmetry

6.6.8. tracer.geometry.surface.rectangular_surface¶

class optrace.tracer.geometry.surface.rectangular_surface.RectangularSurface(dim, **kwargs)¶

Create a rectangular surface, perpendicular to the z-axis.

Parameters:

dim (list | ndarray) – x and y side length as two element array/list
kwargs – additional keyword arguments for parent classes

edge(nc)¶

Get surface values of the surface edge, assumes a circular edge.

Parameters:: nc (int) – number of points on edge (int)
Returns:: X, Y, Z coordinate arrays (all numpy 2D array)
Return type:: tuple[ndarray, ndarray, ndarray]

flip()¶

flip the surface around the x-axis

Return type:: None

mask(x, y)¶

Get surface mask values. A value of 1 means the surface is defined here.

Parameters:

x (ndarray) – x-coordinate array (numpy 1D or 2D array)
y (ndarray) – y-coordinate array (numpy 1D or 2D array)

Returns:

z-coordinate array (numpy 1D or 2D array, depending on shape of x and y)

Return type:

ndarray

plotting_mesh(N)¶

Get 2D plotting mesh. Note that the values are not gridded, the distance can be arbitrary. The only guarantee is that neighbouring array values are neighbouring values in 3D space. Parameter N has no effect for a slit surface and is only for compatibility to other classes.

Parameters:: N (int) – number of grid values in each dimension (int)
Returns:: X, Y, Z coordinate array (all numpy 2D array)
Return type:: tuple[ndarray, ndarray, ndarray]

random_positions(N)¶

Get random 3D positions on the surface, uniformly distributed

Parameters:: N (int) – number of positions
Returns:: position array, shape (N, 3)
Return type:: ndarray

rotate(angle)¶

rotate the surface around the z-axis

Parameters:: angle (float) – rotation angle in degrees
Return type:: None

property extent: tuple[float, float, float, float, float, float]¶

Surface extent, values for a smallest box encompassing all of the surface

Returns:: tuple of x0, x1, y0, y1, z0, z1

property info: str¶: property string for UI information

rotational_symmetry: bool = False¶: has the surface rotational symmetry?

6.6.9. tracer.geometry.surface.ring_surface¶

class optrace.tracer.geometry.surface.ring_surface.RingSurface(r, ri, **kwargs)¶

Create a ring surface, an area between two concentric circles (also known as annulus)

Parameters:

r (float) – radial size for surface_type=”Conic”, “Sphere”, “Circle” or “Ring” (float)
ri (float) – radius of inner circle for surface_type=”Ring” (float)
kwargs – additional keyword arguments for parent classes

hurb_props(x, y)¶

Calculates the properties for Heisenberg Uncertainty Ray Bending.

Parameters:

x (ndarray) – ray position at surface, x-coordinate
y (ndarray) – ray position at surface, y-coordinate

Returns:

distances axis 1, distances axis 2, minor axis vector, ray mask for rays to bend

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

mask(x, y)¶

Get surface mask values. A value of 1 means the surface is defined here.

Parameters:

x (ndarray) – x-coordinate array (numpy 1D or 2D array)
y (ndarray) – y-coordinate array (numpy 1D or 2D array)

Returns:

z-coordinate array (numpy 1D or 2D array, depending on shape of x and y)

Return type:

ndarray

plotting_mesh(N)¶

Get 2D plotting mesh. Note that the values are not gridded, the distance can be arbitrary. The only guarantee is that neighbouring array values are neighbouring values in 3D space.

Parameters:: N (int) – number of grid values in each dimension (int)
Returns:: X, Y, Z coordinate array (all numpy 2D array)
Return type:: tuple[ndarray, ndarray, ndarray]

random_positions(N)¶

Get random 3D positions on the surface, uniformly distributed.

Parameters:: N (int) – number of positions
Returns:: position array, shape (N, 3)
Return type:: ndarray

property info: str¶: info message describing the surface

rotational_symmetry: bool = True¶: has the surface rotational symmetry?

6.6.10. tracer.geometry.surface.slit_surface¶

class optrace.tracer.geometry.surface.slit_surface.SlitSurface(dim, dimi, **kwargs)¶

Create a rectangular surface, perpendicular to the z-axis.

Parameters:

dim (list | ndarray) – x and y side outer length as two element array/list
dimi (list | ndarray) – x and y side slit lengths as two element array/list
kwargs – additional keyword arguments for parent classes

hurb_props(x, y)¶

Calculates the properties for Heisenberg Uncertainty Ray Bending.

Parameters:

x (ndarray) – ray position at surface, x-coordinate
y (ndarray) – ray position at surface, y-coordinate

Returns:

distances axis 1, distances axis 2, left-right axis vector, ray mask for rays to bend

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

mask(x, y)¶

Get surface mask values. A value of 1 means the surface is defined here.

Parameters:

x (ndarray) – x-coordinate array (numpy 1D or 2D array)
y (ndarray) – y-coordinate array (numpy 1D or 2D array)

Returns:

z-coordinate array (numpy 1D or 2D array, depending on shape of x and y)

Return type:

ndarray

plotting_mesh(N)¶

Parameters:: N (int) – number of grid values in each dimension (int)
Returns:: X, Y, Z coordinate array (all numpy 2D array)
Return type:: tuple[ndarray, ndarray, ndarray]

property info: str¶: property string for UI information

6.6.11. tracer.geometry.surface.spherical_surface¶

class optrace.tracer.geometry.surface.spherical_surface.SphericalSurface(r, R, **kwargs)¶

Create a spherical surface object.

Parameters:

R (float) – curvature circle for surface_type=”Conic” or “Sphere” (float)
r (float) – radial size for surface_type=”Conic”, “Sphere”, “Circle” or “Ring” (float)
kwargs – additional keyword arguments for parent classes

sphere_projection(p, projection_method='Equidistant')¶

Sign convention: projection coordinates are positive, when they point in the same direction as cartesian coordinates for the corresponding axis. E.g: cartesian coordinates x = +5, y = -2 relative to sphere center would have some projection coordinate px > 0, py < 0

Parameters:

p (ndarray) – cartesian positions in 3D space
projection_method (str) – one of sphere_projection_methods defined in this class

Returns:

projected coordinates, same shape as input

Return type:

ndarray

property info: str¶: property string for UI information

rotational_symmetry: bool = True¶: has the surface rotational symmetry?

sphere_projection_methods: list[str] = ['Equidistant', 'Orthographic', 'Equal-Area', 'Stereographic']¶: projection methods for mapping a sphere surface onto a plane

6.6.12. tracer.geometry.surface.surface¶

class optrace.tracer.geometry.surface.surface.Surface(r, **kwargs)¶

Create a surface object, parent class of all other surface types.

Parameters:

r (float) – surface radius
kwargs – additional keyword arguments for parent classes

edge(nc)¶

Get surface values of the surface edge.

Parameters:: nc (int) – number of points on edge (int)
Returns:: X, Y, Z coordinate arrays (all numpy 2D array)
Return type:: tuple[ndarray, ndarray, ndarray]

find_hit(p, s)¶

Find the position of hits on surface using the iterative regula falsi algorithm.

Parameters:

p (ndarray) – position array (numpy 2D array, shape (N, 3))
s (ndarray) – direction array (numpy 2D array, shape (N, 3))

Returns:

positions of hit (shape as p), bool numpy 1D array if ray hits lens, indices of ill-conditioned rays

Return type:

tuple[ndarray, ndarray, ndarray]

flip()¶

flip the surface around the x-axis

Return type:: None

is_flat()¶

Returns:: if the surface has no extent in z-direction
Return type:: bool

mask(x, y)¶

Get surface mask values. A value of 1 means the surface is defined here.

Parameters:

x (ndarray) – x-coordinate array (numpy 1D or 2D array)
y (ndarray) – y-coordinate array (numpy 1D or 2D array)

Returns:

z-coordinate array (numpy 1D or 2D array, depending on shape of x and y)

Return type:

ndarray

move_to(pos)¶

Moves the surface in 3D space.

Parameters:: pos (list | ndarray) – 3D position to move to (list or numpy 1D array)
Return type:: None

normals(x, y)¶

Get normal vectors of the surface.

Parameters:

x (ndarray) – x-coordinates (numpy 1D array)
y (ndarray) – y-coordinates (numpy 1D array)

Returns:

normal vector array of shape (x.shape[0], 3), components in second dimension (numpy 2D array)

Return type:

ndarray

plotting_mesh(N)¶

Get 2D plotting mesh. Note that the values are not gridded, the distance can be arbitrary. The only guarantee is that neighbouring array values are neighbouring values in 3D space.

Parameters:: N (int) – number of grid values in each dimension (int)
Returns:: X, Y, Z coordinate array (all numpy 2D array)
Return type:: tuple[ndarray, ndarray, ndarray]

rotate(angle)¶

rotate the surface around the z-axis :param angle: rotation angle in degrees

Parameters:: angle (float)
Return type:: None

values(x, y)¶

Get surface values. Absolute coordinates. Points outside the surface are intersected with the radially continued edge.

Parameters:

x (ndarray) – x-coordinate array (numpy 1D or 2D array)
y (ndarray) – y-coordinate array (numpy 1D or 2D array)

Returns:

z-coordinate array (numpy 1D or 2D array, depending on shape of x and y)

Return type:

ndarray

C_EPS: float = 1e-06¶: calculation epsilon. In some numerical methods this is the desired solution precision

N_EPS: float = 1e-10¶: numerical epsilon. Used for floating number comparisons. As well as adding small differences for plotting

property dn: float¶: thickness between center z-position and lowest point on surface

property dp: float¶: thickness between highest point on surface and center z-position

property ds: float¶: surface thickness. Difference between highest and lowest point on surface

property extent: tuple[float, float, float, float, float, float]¶

Surface extent, values for a smallest box encompassing all of the surface

Returns:: tuple of x0, x1, y0, y1, z0, z1

property info: str¶: property string for UI information

rotational_symmetry: bool = False¶: has the surface rotational symmetry? Needs to be overwritten by child classes

6.6.13. tracer.geometry.surface.tilted_surface¶

class optrace.tracer.geometry.surface.tilted_surface.TiltedSurface(r, normal=None, normal_sph=None, **kwargs)¶

Create a tilted surface.

Parameters:

r (float) – radial size of the surface
normal (list | ndarray) – normal vector, list or array of 3 elements
normal_sph (list | ndarray) – spherical normal vector, list or array of 2 elements (theta, phi, both in degrees)
kwargs – additional keyword arguments for parent classes

find_hit(p, s)¶

Find hit/intersections of rays with this surface.

Parameters:

p (ndarray) – ray position array, shape (N, 3)
s (ndarray) – unity ray direction vectors, shape (N, 3)

Returns:

intersection position (shape (N, 3)), boolean array (shape N) declaring a hit, indices of ill-conditioned rays

Return type:

tuple[ndarray, ndarray, ndarray]

flip()¶

flip the surface around the x-axis

Return type:: None

normals(x, y)¶

Get normal vectors of the surface.

Parameters:

x (ndarray) – x-coordinates (numpy 1D array)
y (ndarray) – y-coordinates (numpy 1D array)

Returns:

normal vector array of shape (x.shape[0], 3), components in second dimension (numpy 2D array)

Return type:

ndarray

rotate(angle)¶

rotate the surface around the z-axis

Parameters:: angle (float) – rotation angle in degrees
Return type:: None

property info: str¶: property string for UI information

rotational_symmetry: bool = False¶: has the surface rotational symmetry?