shadow4.optical_surfaces package

Submodules

shadow4.optical_surfaces.s4_conic module

Defines the shadow4 Conic class to deal with conic surfaces (plane, sphere, ellipsoid, paraboloid and hyperboloid).

The conic surface is expressed as F(x,y,z)=0, with F a quadratic function of x, y, and z. In other words

F(x,y,z) = ccc[0]*X^2 + ccc[1]*Y^2 + ccc[2]*Z^2 + ccc[3]*X*Y + ccc[4]*Y*Z + ccc[5]*X*Z + ccc[6]*X + ccc[7]*Y + ccc[8]*Z + ccc[9] = 0

class shadow4.optical_surfaces.s4_conic.S4Conic(ccc=None)

Bases: S4OpticalSurface

Class to manage conic optical surfaces [expressed as a quadratoc polynomial].

Parameters:

ccc (None, list or numpy array.) – Input for the 10 conic coefficients.

calculate_intercept(XIN, VIN)

Calculates the intercept point (or stack of points) for a given ray or stack of rays, given a point XIN and director vector VIN.

Parameters:

• XIN (numpy array) – The coordinates of a point of origin of the ray: shape [3, NRAYS].

• VIN (numpy array) – The coordinates of a director vector the ray: shape [3, NRAYS].

Returns:

The two solutions (time or flight path) as (TPAR1.real, TPAR2.real, IFLAG).

Return type:

tuple

calculate_intercept_and_choose_solution(x1, v1, reference_distance=10.0, method=0)

Calculates the intercept point (or stack of points) for a given ray or stack of rays, given a point XIN and director vector VIN.

Parameters:

• XIN (numpy array) – The coordinates of a point of origin of the ray: shape [3, NRAYS].

• VIN (numpy array) – The coordinates of a director vector the ray: shape [3, NRAYS].

• reference_distance (float, optional) – A reference distance. The selected solution will be the closest to this reference_distance.

• method (int, optional) – 0: automatic selection (essentially the same as in shadow3 but replacing TSOURCE (unavailable here) by reference_distance). 1: use first solution. 2: use second solution.

Returns:

The selected solution (time or flight path) as (t, iflag).

Return type:

tuple

choose_solution(TPAR1, TPAR2, reference_distance=10.0, method=0)

Selects the wanted single solution from the total of solutions.

Parameters:

• TPAR1 (numpy array) – The array with the first solution.

• TPAR2 (numpy array) – The array with the second solution.

• reference_distance (float, optional) – A reference distance. The selected solution is the closer to this reference distance.

• method (int, optional) – 0: new shadow4 way (essentially the same as in shadow3 but replacing TSOURCE (unavailable here) by reference_distance), 1: use first solution, 2: use second solution.

Returns:

The chosen solution.

Return type:

numpy array

duplicate()

Duplicates an instance of S4Conic

Return type:

instance of S4Conic.

get_coefficients()

Returns the conic coefficients.

Returns:

the conic coefficients (copy).

Return type:

numpy array

get_normal(x2)

Calculates the normal vector (or stack of vectors) at a point on the surface.

Parameters:

x2 (numpy array) – The coordinates vector(s) of shape [3, NRAYS].

Returns:

The normal vector(s) of shape [3, NRAYS].

Return type:

numpy array

height(y=0, x=0, return_solution=0)

Calculates a 2D mesh array with the surface heights. (The same as surface_height but x,y interchanged!).

Parameters:

• y (float (a scalar, vector or mesh), optional) – The y coordinate(s).

• x (float (a scalar, vector or mesh)) – The x coordinate(s).

return_solutionint, optional

Flag: 0 = guess the solution with zero at pole, 1 = get first solution, 2 = get second solution.

Returns:

the height scalar/vector/mesh depending on inputs.

Return type:

2D numpy array

Notes

y and x must be homogeneous, otherwise an error will occur:

• both scalars

• both mesh

• one scalar and another vector

info()

Creates an info text.

Return type:

str

classmethod initialize_as_ellipsoid_from_external_parameters(AXMAJ, AXMIN, ELL_THE, cylindrical=0, cylangle=0.0, switch_convexity=0)

Create an instance of S4Conic representing a ellipsoid from external parameters.

Parameters:

• AXMAJ (float) – The major axis of the ellipsoid in m (a).

• AXMIN (float) – The minor axis of the ellipsoid in m (b).

• ELL_THE (float) – The angle from the line joining the center of the ellipsoid with the mirror pole to the major axis (CCW).

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

Return type:

instance of S4Conic

classmethod initialize_as_ellipsoid_from_focal_distances(p, q, theta1, cylindrical=0, cylangle=0.0, switch_convexity=0, method=1)

Creates an instance of S4Conic representing an ellipsoid from factory parameters (p, q, theta).

Parameters:

• p (float) – The distance from the source to the mirror pole in m.

• q (float) – The distance from the mirror pole to the image in m.

• theta_grazing (float) – The grazing angle in deg.

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

• method (int, optional) – See reference, 0: use Table 5, 1: use table 4.

Return type:

Instance of S4Conic

References

“Conic Surfaces and Transformations for X-Ray Beamline Optics Modeling”, M. Sanchez del Rio and K. Goldberg, (2024) https://doi.org/10.48550/arXiv.2406.04079

classmethod initialize_as_hyperboloid_from_external_parameters(AXMAJ, AXMIN, ELL_THE, cylindrical=0, cylangle=0.0, switch_convexity=0)

Create an instance of S4Conic representing a hyperboloid from external parameters.

Parameters:

• AXMAJ (float) – The major axis of the ellipsoid in m (a).

• AXMIN (float) – The minor axis of the ellipsoid in m (b).

• ELL_THE (float) – The angle from the line joining the center of the ellipsoid with the mirror pole to the major axis (CCW).

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

Return type:

instance of S4Conic

classmethod initialize_as_hyperboloid_from_focal_distances(p, q, theta1, cylindrical=0, cylangle=0.0, switch_convexity=0, method=0)

Creates an instance of S4Conic representing a hyperboloid from factory parameters (p, q, theta).

Parameters:

• p (float) – The distance from the source to the mirror pole in m.

• q (float) – The distance from the mirror pole to the image in m.

• theta_grazing (float) – The grazing angle in deg.

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

• method (int, optional) – See reference, 0: use Table 5, 1: use table 4.

Return type:

Instance of S4Conic

References

“Conic Surfaces and Transformations for X-Ray Beamline Optics Modeling”, M. Sanchez del Rio and K. Goldberg, (2024) https://doi.org/10.48550/arXiv.2406.04079

classmethod initialize_as_paraboloid_from_external_parameters(parabola_parameter, cylindrical=0, cylangle=0.0, switch_convexity=0)

Create an instance of S4Conic representing a paraboloid from external parameters.

Parameters:

• parabola_parameters (float) – The parabola parameter in m.

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

Return type:

instance of S4Conic

classmethod initialize_as_paraboloid_from_focal_distances(p, q, theta1, cylindrical=0, cylangle=0.0, switch_convexity=0, method=1)

Creates an instance of S4Conic representing a paraboloid from factory parameters (p, q, theta).

Parameters:

• p (float) – The distance from the source to the mirror pole in m.

• q (float) – The distance from the mirror pole to the image in m.

• theta_grazing (float) – The grazing angle in deg.

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

• method (int, optional) – See reference, 0: use Table 5, 1: use table 4.

Return type:

Instance of S4Conic

References

“Conic Surfaces and Transformations for X-Ray Beamline Optics Modeling”, M. Sanchez del Rio and K. Goldberg, (2024) https://doi.org/10.48550/arXiv.2406.04079

classmethod initialize_as_plane()

Create an instance of S4Conic representing a plane.

Return type:

instance of S4Conic

classmethod initialize_as_sphere_from_external_parameters(radius, cylindrical=0, cylangle=0.0, switch_convexity=0)

Create an instance of S4Conic representing a sphere (defined from external parameters, i.e. the radius).

Parameters:

• radius (float) – The sphere radius in m.

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

Return type:

instance of S4Conic

classmethod initialize_as_sphere_from_focal_distances(p, q, theta_grazing, cylindrical=0, cylangle=0.0, switch_convexity=0)

Creates an instance of S4Conic representing a sphere from factory parameters (p, q, theta).

Parameters:

• p (float) – The distance from the source to the mirror pole in m.

• q (float) – The distance from the mirror pole to the image in m.

• theta_grazing (float) – The grazing angle in deg.

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

Return type:

instance of S4Conic

classmethod initialize_from_coefficients(ccc)

Create an instance of S4Conic from the coefficients.

Parameters:

ccc (None, list or numpy array.) – Input for the 10 conic coefficients.

Return type:

instance of S4Conic

classmethod rotate_and_translate_coefficients(coe_list, R_M, T)

Perform rotation and translation of the conic coefficients [rf]

Parameters:

• coe_list (list) – A list with the 10 conic coefficients.

• R (list) – The rotation matrix (e.g. identity is [[1,0,0],[0,1,0],[0,0,1]] )

• T (list) – Translation vector (e.t. [0,0,0])

Returns:

The rotated coefficients

Return type:

list

References

[rf]

“Conic Surfaces and Transformations for X-Ray Beamline Optics Modeling”, M. Sanchez del Rio and K. Goldberg,

2024. https://doi.org/10.48550/arXiv.2406.04079

set_coefficients(ccc)

Sets the conic coefficients.

Parameters:

ccc (None, list or numpy array.) – Input for the 10 conic coefficients.

set_ellipsoid_from_external_parameters(AXMAJ, AXMIN, ELL_THE)

Sets the conic coefficients for an ellipsoid given the external parameters (as defined in SHADOW3).

Parameters:

• AXMAJ (float) – The major axis of the ellipsoid in m (a).

• AXMIN (float) – The minor axis of the ellipsoid in m (b).

• ELL_THE (float) – The angle from the line joining the center of the ellipsoid with the mirror pole to the major axis (CCW).

set_hyperboloid_from_external_parameters(AXMAJ, AXMIN, ELL_THE)

set_paraboloid_from_external_parameters(parabola_parameter)

set_sphere_from_external_parameters(rmirr)

Sets the conic coefficients for a sphere.

Parameters:

rmirr (float) – The radius of the sphere in m.

surface_height(x, y, return_solution=0)

Calculates a 2D mesh array with the surface heights.

Parameters:

• x (float (a scalar, vector or mesh)) – The x coordinate(s).

• y (float (a scalar, vector or mesh)) – The y coordinate(s).

• return_solution (int, optional) – Flag: 0 = guess the solution with zero at pole, 1 = get first solution, 2 = get second solution.

Returns:

the height scalar/vector/mesh depending on inputs.

Return type:

2D numpy array

Notes

x and y must be homogeneous, otherwise an error will occur:

• both scalars

• both mesh

• one scalar and another vector

shadow4.optical_surfaces.s4_mesh module

Defines the shadow4 Mesh class to deal with a numerical surfaces (defined by an array of points).

class shadow4.optical_surfaces.s4_mesh.S4Mesh(surface: Callable = None, mesh_x: ndarray = None, mesh_y: ndarray = None, mesh_z: ndarray = None)

Bases: S4OpticalSurface

Class to manage optical surfaces defined by numeric arrays.

Parameters:

• surface (callable, optional) – A function to return the surface height z from coordinates x, y as arguments. Nor needed if mesh_* are given.

• mesh_x (numpy array, optional) – The array with the X coordinate in m. Nor used if surface is given.

• mesh_y (numpy array, optional) – The array with the X coordinate in m. Nor used if surface is given.

• mesh_z (numpy array, optional) – The array with the X coordinate in m. Nor used if surface is given.

add_to_mesh(z1: int | float | ndarray)

Add a new numerical mesh to the existing one.

Parameters:

z1 (int, float, or numpy array) – The 2D Mesh (or the scalar value).

calculate_intercept(XIN: ndarray, VIN: ndarray, keep=0)

Calculates the intercept point (or stack of points) for a given ray or stack of rays, given a point XIN and director vector VIN.

Parameters:

• XIN (numpy array) – The coordinates of a point of origin of the ray: shape [3, NRAYS].

• VIN (numpy array) – The coordinates of a director vector the ray: shape [3, NRAYS].

Returns:

(answer, i_flag) The selected solution (time or flight path numpy array) and the flag numpy array.

Return type:

tuple

calculate_intercept_and_choose_solution(x1: ndarray, v1: ndarray, reference_distance: float = 10.0, method: int = 0)

Calculates the intercept point (or stack of points) for a given ray or stack of rays, given a point XIN and director vector VIN.

Parameters:

• XIN (numpy array) – The coordinates of a point of origin of the ray: shape [3, NRAYS].

• VIN (numpy array) – The coordinates of a director vector the ray: shape [3, NRAYS].

• reference_distance (float, optional) – Not used in S4Mesh.

• method (int, optional) – Not used in S4Mesh.

Returns:

(answer, i_flag) The selected solution (time or flight path numpy array) and the flag numpy array.

Return type:

tuple

duplicate()

Duplicates an instance of S4Toroid

Return type:

instance of S4Toroid.

get_mesh_x_y() → Tuple[ndarray, ndarray]

Returns the x and y arrays.

Returns:

• tuple

• (x, y) numpy 1D arrays.

get_mesh_z() → ndarray

returns the z 2D array.

Return type:

numpy 2D array

get_normal(x2: ndarray)

Calculates the normal vector (or stack of vectors) at a point on the surface.

Parameters:

x2 (numpy array) – The coordinates vector(s) of shape [3, NRAYS].

Returns:

The normal vector(s) of shape [3, NRAYS].

Return type:

numpy array

info()

Creates an info text.

Return type:

str

load_file(filename: str)

Loads a numeric mesh from an text file (with the SHADOW3 presurface preprocessor format).

Parameters:

filename (str) – The file name.

load_h5file(filename: str)

Loads a numeric mesh from an hdf5 file (with the standard OASYS surface description).

Parameters:

filename (str) – The file name.

load_surface_data(surface_data_object)

Loads a numeric mesh from an OASYS surface data object.

Parameters:

filename (instance of OasysSurfaceData) – The data object.

load_surface_data_arrays(x: ndarray, y: ndarray, Z: ndarray)

Loads a numeric mesh from arrays.

Parameters:

• x (numpy array) – 1D array with the x coordinates in m.

• y (numpy array) – 1D array with the y coordinates in m.

• Z (numpy array) – 2D array with the z(x,y) coordinates in m.

surface_height(x: float | ndarray, y: float | ndarray)

Calculates a 2D mesh array with the surface heights.

Parameters:

• x (float or numpy 2D array (mesh)) – The x coordinate(s).

• y (float or numpy 2D array) – The y coordinate(s).

Returns:

the height mesh.

Return type:

2D numpy array

shadow4.optical_surfaces.s4_optical_surface module

Abstract class defining the interfaces of the optical surfaces to be implemented in the subclasses.

It also defines common utilities to write the surfaces to files.

class shadow4.optical_surfaces.s4_optical_surface.S4OpticalSurface

Bases: object

Base class to manage optical surfaces [subclasses are S4Conic, S4Toroid, S4Mesh].

apply_grating_diffraction_on_beam(beam, ruling=[0.0], order=0, f_ruling=0, invert_normal=1)

Computes

• the intersection of the incident beam (expressed in local coordinates to the beamline element) with

optical element; and

• the output direction based on the Grating scattering.

Parameters:

• beam (S4Beam instance, optional) – The input beam

• order (int, optional) – The diffraction order, e.g. -1, 1, or 0.

• f_ruling (list) – the ruling coefficients, e.g., [800000] for a grating with uniform ruling of 800 lines per mm.

• invert_normal (int, optional) – We need the outward normal. In case that the calculated normal is inwards (like in S4Conic), set this flag to one. In other cases when the calculated normal is outward (like S4Mesh) set to 0.

Returns:

• tuple – (newbeam, normal) The footprint beam, the array with the normal direction with shape (3, npoints).

• Notes

• ——

• It uses arrayofvectors/vector_refraction()

apply_refraction_on_beam(beam, refraction_index_object, refraction_index_image, apply_attenuation=0, linear_attenuation_coefficient=0.0)

Computes

• the intersection of the incident beam (expressed in local coordinates to the beamline element) with

optical element; and

• the output direction based on the Snell law of refraction.

Parameters:

beam (S4Beam instance) – The input beam

Returns:

• tuple – (newbeam, normal, t, x1, v1, x2, v2) The footprint beam, the array with the normal direction with shape (3, npoints), the time of flight or travelled path; and the incident points, incident direction, intercept points, and output direction, all arrays with shape shape (3, npoints).

• Notes

• ——

• It uses arrayofvectors/vector_refraction()

apply_specular_reflection_on_beam(beam)

Computes

the intersection of the incident beam (expressed in local coordinates to the beamline element) with optical element; and

the output direction based on the laws of specular reflection:

• The angle of incidence (the angle between the incoming light ray and the normal to the surface) is equal to

the angle of reflection (the angle between the reflected light ray and the normal)

• The incident ray, the reflected ray, and the normal to the surface at the point of incidence all lie in the same plane.

In vector form, given

• Incident vector: i (pointing towards the surface)

• Normal vector: n (perpendicular to the surface, of unit length)

• Reflected vector: r (pointing away from the surface)

The relationship between these vectors is: r = i - 2(i · n) n

Parameters:

beam (S4Beam instance) – The input beam

Returns:

• tuple – (newbeam, normal, t, x1, v1, x2, v2) The footprint beam, the array with the normal direction with shape (3, npoints), the time of flight or travelled path; and the incident points, incident direction, intercept points, and output direction, all arrays with shape shape (3, npoints).

• Notes

• ——

• It uses arrayofvectors/vector_reflection()

calculate_intercept(XIN, VIN, **kwargs)

To be implemented in derived classes.

Return type:

NotImplementedError

calculate_intercept_and_choose_solution(XIN, VIN, **kwargs)

To be implemented in derived classes.

Return type:

NotImplementedError

calculate_intercept_on_beam(beam)

Computes the intersection of the incident beam (expressed in local coordinates to the beamline element) with optical element.

Parameters:

beam (S4Beam instance) – The input beam

Returns:

• tuple – (footprint, normal): The footprint beam and the array with the normal direction with shape (3, npoints).

• Notes

• ——

• It uses arrayofvectors/vector_reflection()

choose_solution(TPAR1, TPAR2, **kwargs)

To be implemented in derived classes.

Return type:

NotImplementedError

duplicate()

To be implemented in derived classes.

Return type:

NotImplementedError

get_normal(x, **kwargs)

To be implemented in derived classes.

Return type:

NotImplementedError

info()

To be implemented in derived classes.

Return type:

NotImplementedError

surface_height(x, y, **kwargs)

To be implemented in derived classes.

Return type:

NotImplementedError

write_mesh_file(x, y, filename='surface.dat')

Writes the optical surface in a file with SHADOW3 format (presurface preprocessor). The arrays for the x and y coordinates should be provided to evaluate the height z(x, y).

Parameters:

• x (numpy array) – The array with the X coordinates.

• y (numpy array) – The array with the Y coordinates.

• filename (str, optional) – The file name (for output).

Returns:

1=Succes, 0=Error

Return type:

int

write_mesh_h5file(x, y, filename='surface.h5', subgroup_name='surface_file', overwrite=True)

Writes the optical surface in a hdf5 file. The arrays for the x and y coordinates should be provided to evaluate the height z(x, y).

Parameters:

• x (numpy array) – The array with the X coordinates.

• y (numpy array) – The array with the Y coordinates.

• filename (str, optional) – The file name (for output).

• subgroup_name (str, optional) – The h5 subgroup name (surface_file for OASYS compatibility).

• overwrite (int, optional) – Fleg to overwritte file: 0=Append to existing, 1=Overwrite existing file.

classmethod write_shadow_surface(s, xx, yy, outFile='presurface.dat')

Writes a mesh in the SHADOW3/presurface format

Parameters:

• s (numpy array) – The array with the heights s(xx, yy) in m.

• xx (numpy array) – The array with the X spatial coordinates (sagittal, along mirror width) in m.

• yy (numpy array) – The array with the Y spatial coordinates (tangential, along mirror length.) in m.

• outFile (str, optional) – The file name (for output).

Returns:

1=Succes, 0=Error

Return type:

int

shadow4.optical_surfaces.s4_toroid module

Defines the shadow4 Toroid class to deal with a toroidal surface (Quartic equation).

class shadow4.optical_surfaces.s4_toroid.S4Toroid(r_maj=10000000000.0, r_min=10000000000.0, f_torus=0)

Bases: S4OpticalSurface

Class to manage toroidal optical surfaces [expressed as a quartic polynomial].

Parameters:

• r_maj (float, optional) –

  Toroid major radius in m. Note that this is not the tangential radius mut the radius of

  the toroidal axis, therefore for the usual case of concave surface it is the tangential radius minus the sagittal radius.

• r_min (float, optional) – Toroid minor radius (sagittal) in m.

• f_torus (int, optional) – A flag to indicate the mirror pole location within the toroid: - (0): lower/outer (concave/concave), - (1): lower/inner (concave/convex), - (2): upper/inner (convex/concave), - (3): upper/outer (convex/convex).

References

See a graphic in Pag 26 of https://github.com/srio/shadow3-docs/blob/master/doc/shadow-trace.pdf

calculate_intercept(XIN, VIN, vectorize=0, do_test_solution=0)

Calculates the intercept point (or stack of points) for a given ray or stack of rays, given a point XIN and director vector VIN.

Parameters:

• XIN (numpy array) – The coordinates of a point of origin of the ray: shape [3, NRAYS].

• VIN (numpy array) – The coordinates of a director vector the ray: shape [3, NRAYS].

• vectorize (int, optional) –

  Flag:

  • 0 use vectorized numpy (default)

  • 1 use numpy polynomial.polyroots iteratively to compute solutions.

  • 2 New method, vectorized, exact solution of 4th degree eq. It fails in some cases.

  • 3 Like 1, but iterated (not vectorized). It fails in some cases.

  • 4 Use fqs modified library as in srxraylib. It does not work.

• do_test_solution (int, optional) – Flag to test the solutions (substitute in the polynomial and check if result is zero): 0=No, 1=Yes.

Returns:

(t0, t1, t2, t3) The four solutions of the quartic equation (time or flight path).

Return type:

tuple

calculate_intercept_and_choose_solution(x1, v1, reference_distance=0.0, method=0, use_newton_solution=0)

Calculates the intercept point (or stack of points) for a given ray or stack of rays, given a point XIN and director vector VIN. Uses the exact solutions of the quartic equation (intersection torus ray).

Parameters:

• XIN (numpy array) – The coordinates of a point of origin of the ray: shape [3, NRAYS].

• VIN (numpy array) – The coordinates of a director vector the ray: shape [3, NRAYS].

• reference_distance (float, optional) – Not used in S4Toroid.

• method (int, optional) – Not used in S4Toroid.

• use_newton_solution (int, optional) – Calculate solution using the exact (0) or approximated Newton method (1). In this case, reference_distance is used as a first solution guess.

Returns:

The selected solution (time or flight path).

Return type:

numpy array

calculate_intercept_and_choose_solution_newton(x1, v1, reference_distance=0.0, method=0)

Calculates the intercept point (or stack of points) for a given ray or stack of rays, given a point XIN and director vector VIN. Uses the Newton approximated solution.

Parameters:

• XIN (numpy array) – The coordinates of a point of origin of the ray: shape [3, NRAYS].

• VIN (numpy array) – The coordinates of a director vector the ray: shape [3, NRAYS].

• reference_distance (float, optional) – The initial solution guess.

• method (int, optional) – Not used in S4Toroid.

Returns:

The selected solution (time or flight path).

Return type:

numpy array

choose_solution(t0, t1, t2, t3, vectorize=2, zero_below=1e-06)

Selects the wanted single solution from the total of solutions.

Parameters:

• t0 (numpy array) – The array with the first solution.

• t1 (numpy array) – The array with the second solution.

• t2 (numpy array) – The array with the thirs solution.

• t3 (numpy array) – The array with the fourth solution.

• reference_distance (float, optional) – A reference distance. The selected solution is the closer to this reference distance.

• vectorize (int, optional) – 0: iterative (loop) method, 1: use vectorized method. 2: use another vectorized method (slower than 1).

• zero_below (float, optional) – A level of zero for intermediate step in finding the solutions using vectorized=1.

Returns:

The chosen solution.

Return type:

numpy array

duplicate()

Duplicates an instance of S4Toroid

Return type:

instance of S4Toroid.

get_normal(x2)

Calculates the normal vector (or stack of vectors) at a point on the surface.

Parameters:

x2 (numpy array) – The coordinates vector(s) of shape [3, NRAYS].

Returns:

The normal vector(s) of shape [3, NRAYS].

Return type:

numpy array

get_tangential_and_sagittal_radii(signed=0)

Gets the radii of the focusing surface.

Parameters:

signed (int, optional) – Flag (0): returns all positive values, (1): return negative value if radius is convex

Returns:

• tuple

• (r_rangential, r_sagittal) in m.

get_toroid_radii()

Gets the toroid radii r_maj, r_min. Note that r_maj is not the tangential radius!

Returns:

• tuple

• (r_maj, r_min) Note that r_maj is not the tangential radius!

info()

Creates an info text.

Return type:

str

set_cylindrical(CIL_ANG)

set_f_torus(f_torus=0)

Sets the flag for the selected section of the toroid.

Parameters:

f_torus (int, optional) – A flag to indicate the mirror pole location within the toroid: - (0): lower/outer (concave/concave), - (1): lower/inner (concave/convex), - (2): upper/inner (convex/concave), - (3): upper/outer (convex/convex).

set_from_focal_distances(ssour, simag, theta_grazing)

Sets the toroid radii from factory parameters (p, q, theta).

Parameters:

• p (float) – The distance from the source to the mirror pole in m.

• q (float) – The distance from the mirror pole to the image in m.

• theta_grazing (float) – The grazing angle in deg.

• cylindrical (int, optional) – Flag: 0=the surface is curved in both directions. 1=the surface is flat in one direction.

• cylangle (float, optional) – For cylindrical=1, the angle of the cylinder axis with the X axis (CCW).

• switch_convexity (int, optional) – Flag to indicate that the convexity os inverted.

Return type:

instance of S4Conic

set_tangential_and_sagittal_radii(rtan, rsag)

Sets the toroid radii from the tangential and sagittal radius.

Parameters:

• rtan (float) – The surface tangential radius in m.

• rsag (float) – The surface sagittal radius in m.

set_toroid_radii(r_maj, r_min)

Sets the toroid radii.

Parameters:

• r_maj (float) – The toroi major radius in m (This is **not* the tangential radius).

• r_min (float) – The toroi minur radius in m.

surface_height(X, Y, solution_index=-1, method=2)

Calculates a 2D mesh array with the surface heights.

Parameters:

• X (numpy 2D array (mesh)) – The x coordinate(s).

• Y (numpy 2D array) – The y coordinate(s).

• method (int, optional) – 0 = use a fast direct method to solve the quartic equation, 1 = use self.calculate_intercept (TODO: most times it does not work, problems in finding the roots). 2 = Just add the tangential and sagittal circular profiles.

• solution_index (int, optional) – For method=0,1, the index of the solution used for creating the height map: * -1 = take the solution according with f_torus, * 0 = get the first solution, * 1 = get the second solution, * 2 = get the third solution, * 3 = get the fourth solution.

Returns:

the height mesh.

Return type:

2D numpy array

switch_convexity()

Module contents