shadow4.beam package

Submodules

shadow4.beam.s4_beam module

Defines the shadow4 beam and associated methods and utilities.

VERY IMPORTANT: Column 11 (index 10) is wavenumber (cm^-1) as internally in Shadow.

Photon energy in eV is now column 26 (index 25).

class shadow4.beam.s4_beam.S4Beam(N=1000, array=None, N_cleaned=None)

Bases: object

Implements a beam. Internally it is an array of N rays and 18 columns.

Parameters:

• N (int, optional) – The number of rays. Not used if array is defined.

• array (numpy array, optional) – The numpy array (N, 18) with the data.

• N_cleaned (None or int, optional) –

  To initialize a beam with an array that comes from a beam “cleaned from its lost rays”, input here the total number of rays including the lost rays (it should be > array.shape[0]).

  Typically this keyword is not used (i.e. leave the default N_cleaned=None).

See also

shadow4.S4Beam.column_names

columns contents.

property N

Returns the total number of rays.

Returns:

The total number of rays.

Return type:

int

property Nbad

Returns the number of STORED bad rays (see Notes in get_number_of_rays()).

Returns:

The number of bad rays.

Return type:

int

property Ngood

Returns the number of good rays.

Returns:

The number of good rays.

Return type:

int

property Nstored

Returns the number of stored rays (rays.shape[0]).

Returns:

The number of stored rays.

Return type:

int

add_phase_p(phase)

Add a pi-phase to the beam.

Parameters:

phase (float) – phase angle in rad.

add_phase_s(phase)

Add a sigma-phase to the beam.

Parameters:

phase (float) – phase angle in rad.

add_phases(phase_s, phase_p)

Add a sigma and pi phases to the beam.

Parameters:

• phase_s (float) – The sigma phase in rad.

• phase_p (float) – the pi phase in rad.

append_beam(beam_to_append, update_column_index=True)

Appends the rays of an extra given beam.

Parameters:

• beam_to_append (instance of S4Beam) – The beam which rays are going to be appended.

• update_column_index (bool) – If True, the indices (from the index column 12) of the appended beam are changed to concatenate the existing indices. If False there is no change (therefore resulting in duplicated indices).

apply_attenuation(att1)

Apply an attenuation factor to the beam.

Parameters:

att1 (float or numpy array) – The attenuator factor in amplitude (real).

apply_boundaries_shadow(fhit_c=0, fshape=1, rlen1=0.0, rlen2=0.0, rwidx1=0.0, rwidx2=0.0, flag_lost_value=-1)

Apply boundaries using the shadow3 flags and variables.

Parameters:

• fhit_c (int, optional) – flag: mirror dimensions finite: yes (1), no(0).

• fshape (int, optional) –

  for fhit_c=1: mirror shape rectangular (1)

  full ellipse (2) ellipse with hole (3).

• rlen1 (float, optional) – fshape=1: mirror half length +Y. fshape=3: internal minor axis (Y).

• rlen2 (float, optional) – fshape=1: mirror half length -Y. fshape=2,3: external outline minor

• rwidx1 (float, optional) – fshape=1: mirror half width +X. fshape=3: internal major axis (X).

• rwidx2 (float, optional) – fshape=1: mirror half width -X. fshape=2,3: external outline major axis (X).

• flag_lost_value (float, optional) – the value to be assigned to the flagged bad rays.

apply_boundaries_syned(syned_boundary_object, flag_lost_value=-1)

Crops the beam to a shape defined in a syned object.

Parameters:

syned_boundary_object (instance of syned.beamline.shape.Shape) – The cropping shape.

flag_lost_valuefloat, optional

the value to be assigned to the flagged bad rays.

See also

syned.beamline.shape.Shape, --

apply_complex_reflectivities(Rs, Rp)

Apply sigma- and pi- reflectivities to the beam.

Parameters:

• Rs (complex) – The reflectivity value.

• Rp (complex) – The reflectivity value.

apply_complex_reflectivity_p(Rp)

Apply pi-reflectivity to the beam.

Parameters:

Rp (complex) – The reflectivity value.

apply_complex_reflectivity_s(Rs)

Apply sigma-reflectivity to the beam.

Parameters:

Rs (complex) – The reflectivity value.

apply_reflectivities(Rs, Rp)

Apply sigma- and pi- reflectivities to the beam.

Parameters:

• Rs (float) – The reflectivity value (real number, if complex, use apply_complex_reflectivities()).

• Rp (float) – The reflectivity value (real number, if complex, use apply_complex_reflectivities()).

apply_reflectivity_p(Rp)

Apply pi-reflectivity to the beam.

Parameters:

Rp (float) – The reflectivity value (real number, if complex, use apply_complex_reflectivity_p()).

apply_reflectivity_s(Rs)

Apply sigma-reflectivity to the beam.

Parameters:

Rs (float) – The reflectivity value (real number, if complex, use apply_complex_reflectivity_s()).

calculate_hew(nolost=0, bins=100)

Calculate HEW (Half Energy Width) for the Horizontal and Vertical angles (columns 4 and 6) :param nbins: number of bins of the histogram. :type nbins: int, optional :param nolost:

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

Returns:

The hew values (in radians).

Return type:

tuple

calculate_hew_x(nolost=0, bins=100)

Calculate HEW (Half Energy Width) for the Horizontal angle (column 4) :param nbins: number of bins of the histogram. :type nbins: int, optional :param nolost:

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

Returns:

The hew value (in radians).

Return type:

float

calculate_hew_z(nolost=0, bins=100)

Calculate HEW (Half Energy Width) for the Vertical angle (column 6) :param nbins: number of bins of the histogram. :type nbins: int, optional :param nolost:

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

Returns:

The hew value (in radians).

Return type:

float

change_to_image_reference_system(theta, T_IMAGE, rad=True, refraction_index=1.0, apply_attenuation=0, linear_attenuation_coefficient=0.0)

Implements the propagation from the mirror reference frame to the screen (image) reference. Mimics IMREF and IMAGE1 subrutines in shadow3

Parameters:

• theta (float) – the grazing angle in rad (default) or deg (if deg=False).

• T_IMAGE (float) – the distance o.e. to image in m.

• rad (boolean, optional) – set False if theta is given in degrees.

• refraction_index (float) – Define the real part of the refraction index.

• apply_attenuation (int, optional) – A flag to indicate that attenuation must be applied (using linear_attenuation_coefficient).

• linear_attenuation_coefficient (float or numpy array) – The attenuation coefficient in m^(-1).

clean_lost_rays()

Clean the lost rays from the beam. It removed the lost rays from the stored beam. It saves memory. Useful when lost rays are not longer interesting.

Returns:

The S4Beam without lost rays.

Return type:

S4Beam instance

classmethod column_names()

returns a list with the names of shadow4 beam columns (the 18 columns in the beam plus the extended columns).

Returns:

The column names.

Return type:

list

classmethod column_names_formatted()

classmethod column_names_formatted_with_column_number()

returns a list with the formatted-names of shadow4 beam columns including the column number (the 18 columns in the beam plus the extended columns).

Returns:

The column names.

Return type:

list

classmethod column_names_with_column_number()

returns a list with the names of shadow4 beam columns including the column number (the 18 columns in the beam plus the extended columns).

Returns:

The column names.

Return type:

list

classmethod column_short_names()

returns a list with the short-names of shadow4 beam columns (the 18 columns in the beam plus the extended columns). Useful for labeling plots.

Returns:

The column short-names.

Return type:

list

classmethod column_short_names_with_column_number()

returns a list with the short-names of shadow4 beam columns including the column number (the 18 columns in the beam plus the extended columns).

Returns:

The column names.

Return type:

list

classmethod column_units()

returns a list with the column units of shadow4 beam columns (the 18 columns in the beam plus the extended columns).

Returns:

The column units.

Return type:

list

crop_ellipse(x_col, a1, a2, y_col, b1, b2, negative=False, flag_lost_value=-1)

Crops the beam to an ellipse along the axes x_col and y_col.

Parameters:

• x_col (int) – column 1 of the cropping surface.

• a1 (float) – minimum for x_col.

• a2 (float) – maximum for x_col.

• y_col (int) – column 2 of the cropping surface.

• b1 (float) – minimum for y_col.

• b2 (float) – maximum for y_col.

• negative (boolean, optional) – makes the negative (i.e. obstruction instead of aperture).

• flag_lost_value (float, optional) – the value to be assigned to the flagged bad rays.

crop_ellipse_with_hole(x_col, a1, a2, a3, a4, y_col, b1, b2, b3, b4, negative=False, flag_lost_value=-1)

Crops the beam to an elliptical annulus along the axes x_col and y_col.

Parameters:

• x_col (int) – column 1 of the cropping surface.

• a1 (float) – inner ellipse minimum for x_col.

• a2 (float) – inner ellipse maximum for x_col.

• a3 (float) – outer ellipse minimum for x_col.

• a4 (float) – outer ellipse maximum for x_col.

• y_col (int) – column 2 of the cropping surface.

• b1 (float) – inner ellipse minimum for y_col.

• b2 (float) – inner ellipse maximum for y_col.

• b3 (float) – outer ellipse minimum for y_col.

• b4 (float) – outer ellipse maximum for y_col.

• negative (boolean, optional) – makes the negative (i.e. obstruction instead of aperture).

• flag_lost_value (float, optional) – the value to be asigned to the flagged bad rays.

crop_rectangle(x_col, x_min, x_max, y_col, y_min, y_max, negative=False, flag_lost_value=-1)

Crops the beam to a rectangle along the axes x_col and y_col.

Parameters:

• x_col (int) – column 1 of the cropping surface.

• x_min (float) – minimum for x_col.

• x_max (float) – maximum for x_col.

• y_col (int) – column 2 of the cropping surface.

• y_min (float) – minimum for y_col.

• y_max (float) – maximum for y_col.

• negative (boolean, optional) – makes the negative (i.e. obstruction instead of aperture).

• flag_lost_value (float, optional) – the value to be assigned to the flagged bad rays.

difference(beam2)

Compares two beams and prints the diferences in different columns.

Parameters:

beam2 (S4 instance) – the beam to compare with.

duplicate()

Duplicates a S4Beam instance.

Returns:

A copy of the S4Beam instance.

Return type:

S4Beam instance

efields_orthogonal(accuracy=1e-10, verbose=0)

Checks orthogonality of electric vector sigma, electric vector pi and divection vector v

Returns:

1=They are orthogonal (correct), 0=not orthogonal (incorrect).

Return type:

int

fixnan(value=0.0)

Replaces nan by zero (or other value).

Parameters:

value (float, optional) – The replacement value.

focnew_coeffs(nolost=1, mode=0, center=[0.0, 0.0])

This is used by the “focnew” tool. Calculate 6 CHI-Square coefficients for the beam array referred to a given origin, in the directions X, Z and combined X-Z. For the X direction we define d = Vy/Vx. The 6 coefficients are: <d**2>, <x d>, <x**2>, <x>**2, <x><d>, <d>**2.

Parameters:

• nolost (int, optional) –

  • 0=uses all rays,

  • 1=uses only good rays (non-lost rays),

  • 2=uses only lost rays.

• mode (int, optional) – A flag to define the center: * 0 = center at origin, * 1 = Center at barycenter (coordinate mean), * 2 = External center.

• center (list or tuple, optional) – The (x,z) coordinates of the center. Used if mode=2.

Returns:

(AX, AZ, AT) The 6 coefficients for the durections X, Z, and average X+Z.

Return type:

tuple

generate_source(source_object)

Put rays that sample a given source_object. This option mimics the obsolete “source” in shadow3. It should not be used, only for compatibility purposes.

Parameters:

source_object (instance of a shadow4.source) – Instance of a source class that implements the get_rays() method.

Returns:

the new source. Note that the calling beam is also modified.

Return type:

S4Beam instance

classmethod get_UVW(X_ROT=0, Y_ROT=0, Z_ROT=0)

returns the rotation matrix given resulting from sequential rotations around the 3 axes X,Y,Z [todo: verify the order]

Parameters:

• X_ROT (float) – rotation angle in rad around the X axis.

• Y_ROT (float) – rotation angle in rad around the Y axis.

• Z_ROT (float) – rotation angle in rad around the Z axis.

Returns:

the 9 matrix elements.

Return type:

tuple

get_average(col, nolost=1, ref=0)

Returns the weighted average of one variable in the beam.

Parameters:

col (int) – The column number.

nolostint, optional

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

refint, optional

ref: 0 = no weight, other value = weight with intensity (col23)

Returns:

the average value.

Return type:

float

get_column(column, nolost=0)

Returns a numpy array with the values of the rays in a given column.

The column number can be 1:18 (stored data) or > 18 for other parameters calculated from the 18 stored ones.

Parameters:

column (int) –

Number of column (starting with 1). Possible choice for column are:

• 1 X spatial coordinate [user’s unit]

• 2 Y spatial coordinate [user’s unit]

• 3 Z spatial coordinate [user’s unit]

• 4 Xp direction or divergence [rads]

• 5 Yp direction or divergence [rads]

• 6 Zp direction or divergence [rads]

• 7 X component of the electromagnetic vector (s-polariz)

• 8 Y component of the electromagnetic vector (s-polariz)

• 9 Z component of the electromagnetic vector (s-polariz)

• 10 Lost ray flag

• 11 wavenumber (2 pi / lambda[cm]) !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

• 12 Ray index

• 13 Optical path length

• 14 Phase (s-polarization) in rad

• 15 Phase (p-polarization) in rad

• 16 X component of the electromagnetic vector (p-polariz)

• 17 Y component of the electromagnetic vector (p-polariz)

• 18 Z component of the electromagnetic vector (p-polariz)

• 19 Wavelength [A]

• 20 R= SQRT(X^2+Y^2+Z^2)

• 21 angle from Y axis

• 22 the magnitude of the Electromagnetic vector

• 23 `|`E`|`^2 (total intensity)

• 24 total intensity for s-polarization

• 25 total intensity for p-polarization

• 26 photon energy in eV !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

• 27 K = 2 pi / lambda * col4 [A^-1]

• 28 K = 2 pi / lambda * col5 [A^-1]

• 29 K = 2 pi / lambda * col6 [A^-1]

• 30 S0-stokes = `|`Es`|`^2 + `|`Ep`|`^2

• 31 S1-stokes = `|`Es`|`^2 - `|`Ep`|`^2

• 32 S2-stokes = 2 |`Es`| |`Ep`| cos(phase_s-phase_p)

• 33 S3-stokes = 2 |`Es`| |`Ep`| sin(phase_s-phase_p)

• 34 Power = intensity(col 23) * energy (col 11)

• 35 Angle-X with Y: |`arcsin(X’)`|

• 36 Angle-Z with Y: |`arcsin(Z’)`|

• 37 Angle-X with Y: |`arcsin(X’) - mean(arcsin(X’))`|

• 38 Angle-Z with Y: |`arcsin(Z’) - mean(arcsin(Z’))`|

• 39 Phase difference in rad: Phase (s-polarization) - Phase (p-polarization)

• 40 Complex amplitude of the electric vector (s-polarization)

• 41 Complex amplitude of the electric vector (p-polarization)

Notes

Column 11 in Shadow3 is column 26 in Shadow4.

nolostint, optional

• 0=return all rays,

• 1=Return only good rays (non-lost rays),

• 2=Return only lost rays.

Returns:

the required array (a copy).

Return type:

numpy array

get_columns(columns, nolost=0)

Returns a numpy array with the values of the rays several selected column.

The column numbers can be 1:18 (stored data) or > 18 for other parameters calculated from the 18 stored ones.

Parameters:

• columns (list) – The number of the columns (column numbers start from 1).

• nolost (int, optional) –

  • 0=return all rays,

  • 1=Return only good rays (non-lost rays),

  • 2=Return only lost rays.

Returns:

the required array (N, len(columns)).

Return type:

numpy array

See also

shadow4.S4Beam.get_column

get_efield_directions(nolost=0)

Computes the directions of the electric vector field.

Parameters:

nolost (int, optional) –

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

Returns:

(e_S, e_P) the directions (array(nrays, 3)) for the S and P components of the electric field.

Return type:

tuple

get_good_range(icol, nolost=0)

Computes a good limits for a given column. Typically used for plots.

Parameters:

• icol (int) – the column number (SHADOW convention, starting from 1)

• nolost (int, optional) –

  • 0=use all rays,

  • 1=use only good rays (non-lost rays),

  • 2=use only lost rays.

Returns:

[rmin,rmax] the selected range

Return type:

list

get_intensity(nolost=0, polarization=0)

Returns a numpy array with the intensities of the rays.

Parameters:

• nolost (int, optional) –

  • 0=return all rays,

  • 1=Return only good rays (non-lost rays),

  • 2=Return only lost rays.

• polarization (int, optional) –

  • 0=total,

  • 1=sigma,

  • 2=pi.

Returns:

The intensities of the rays.

Return type:

numpy array (npoints)

get_jones(nolost=0)

Computes Jones vector.

Parameters:

nolost (int, optional) –

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

Returns:

The two components of the Jones vector for the rays. Shape: (nrays, 2).

Return type:

numpy.array

get_jones_components(nolost=0)

Computes the components Jones vector.

Parameters:

nolost (int, optional) –

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

Returns:

The two components of the Jones vector for the rays (j1, j1).

Return type:

tuple

get_local_directions_sigma_pi(vNormal, vIn=None)

Given a direction N (normal to a surface), this routine calculates the “local sigma and pi” directions, or the unitary vectors perpendicular and parallel to the scattering plane, respectively. The scattering plane is defines as the plane that contains N and the ray direction vIn.

Parameters:

• vNormal (numpy array) – An array of vectors (npoints, 3) with the normal N.

• vIn (numpy array, optional) – The array of vectors with the incident direction. If None, it uses the direction in the S4Beam.

Returns:

• tuple

• (direction_sigma, direction_pi) the two unitary array of vectors with the sigma and pi-directions.

get_number_of_rays(nolost=0)

Returns the number of rays.

Parameters:

nolost (int, optional) –

• 0=return the total number of rays,

• 1=Return the number of good rays (non-lost rays),

• 2=Return the number of STORED lost rays (see Notes).

Notes

Note: in general, when the beam “has not been cleaned” (using clean_lost_rays()) the total number of rays is equal to good raus plus lost rays, and all of them are stored in the beam. If the beam has been cleaned, get_number_of_rays(nolost=2), returns the number of the lost rays that are physically stored in the beam. Calling beam.get_number_of_rays(nolost=2) on a beam that has just been beam.clean_lost_rays() will return zero. It may not be zero if the beam is traced after cleaned and not re-clean.

Returns:

The number of rays.

Return type:

int

get_photon_energy_eV(nolost=0)

Returns a numpy array with the photon energy of the rays in eV.

Parameters:

nolost (int, optional) –

• 0=return all rays,

• 1=Return only good rays (non-lost rays),

• 2=Return only lost rays.

Returns:

The photon energies (in eV) of the rays.

Return type:

numpy array (npoints)

get_photon_wavelength(nolost=0)

Returns a numpy array with the photon energy of the rays in eV.

Parameters:

nolost (int, optional) –

• 0=return all rays,

• 1=Return only good rays (non-lost rays),

• 2=Return only lost rays.

Returns:

The wavelengths (in m) of the rays.

Return type:

numpy array (npoints)

get_rays(nolost=0)

Returns a numpy array (N,18) with the rays.

Parameters:

nolost (int, optional) –

• 0=return all rays,

• 1=Return only good rays (non-lost rays),

• 2=Return only lost rays.

Returns:

The rays.

Return type:

numpy array (npoints,18)

get_standard_deviation(col, nolost=1, ref=0)

Returns the weighted standard deviation of one variable in the beam.

Parameters:

• col (int) – The column number.

• nolost (int, optional) –

  • 0=use all rays,

  • 1=use only good rays (non-lost rays),

  • 2=use only lost rays.

• ref (int, optional) – ref: 0 = no weight, other value = weight with intensity (col23)

Returns:

the st dev.

Return type:

float

histo1(col, xrange=None, nbins=50, nolost=0, ref=0, write=None, factor=1.0, calculate_widths=1, calculate_hew=0)

Calculate the histogram of a column, simply counting the rays, or weighting with another column.

It returns a dictionary which contains the histogram data.

Parameters:

• col (int) – the number of the chosen column.

• xrange (2 elements tuple or list, optional) –

  tuple or list describing the interval of interest for x, the data read from the chosen column.

  (default: None, thus using min and max of the array)

• nbins (int, optional) – number of bins of the histogram.

• nolost (int, optional) –

  • 0=use all rays,

  • 1=use only good rays (non-lost rays),

  • 2=use only lost rays.

• ref (int (or str), optional) –

  • 0, None, “no”, “NO” or “No”: only count the rays.

  • 23, “Yes”, “YES” or “yes”: weight with intensity (look at col=23 |E|^2 total intensity).

  • other value: use that column as weight.

• write (str, optional) – file name with the histogram (default=None, do not write any file).

• factor (float, optional) – a scalar factor to multiply the selected column before histogramming (e.g., for changing scale from cm to um then factor=1e4).

• calculate_widths (int, optional) –

  • 0: do not calculate full-width at half-maximum (FWHM),

  • 1: Do calculate FWHM.

• calculate_hew (int, optional) –

  • 0: do not calculate Half-Energy Width (HEW),

  • 1: Do calculate HEW.

Returns:

a python dictionary with the calculated histogram. Some of the keys are:

’error’, ‘col’, ‘write’, ‘nolost’, ‘nbins’, ‘xrange’, ‘factor’ ‘histogram’, ‘bins’, ‘histogram_sigma’, ‘bin_center’, ‘bin_left’, ‘bin_right’, ‘intensity’, ‘fwhm’, ‘nrays’, ‘good_rays’, ‘lost_rays’.

Return type:

dict

histo2(col_h, col_v, nbins=25, ref=23, nbins_h=None, nbins_v=None, nolost=0, xrange=None, yrange=None, calculate_widths=1)

Performs 2d histogram. Typically used to prepare data for a plotxy plot. It uses histogram2d for calculations.

Note that this shadow4.S4Beam.histo2 was previously called Shadow.Beam.plotxy in shadow3.

Parameters:

• col_h (int) – the horizontal column.

• col_v (int) – the vertical column.

• nbins (int) – The number of bins.

• ref (int (or str), optional) –

  • 0, None, “no”, “NO” or “No”: only count the rays.

  • 23, “Yes”, “YES” or “yes”: weight with intensity (look at col=23 |E|^2 total intensity).

  • other value: use that column as weight.

• nbins_h (int) – number of bins in H.

• nbins_v (int) – number of bins in V.

• nolost (int, optional) –

  • 0=use all rays,

  • 1=use only good rays (non-lost rays),

  • 2=use only lost rays.

• xrange (tuple or list:) – range for H.

• yrange (tuple or list) – range for V.

• calculate_widths (int) –

  • 0=No,

  • 1=calculate FWHM (default),

  • 2=Calculate FWHM and FW at 25% and 75% if Maximum.

Returns:

a dictionary with the histogram and all the data needed (e.g. for a plot).

Return type:

dict

identical(beam2)

Compares two beams

Parameters:

beam2 (S4 instance) – the beam to compare with.

Returns:

True if the two beams are almost equal.

Return type:

boolean

info()

Returns string containing some information of the beam (min, max, center, stDev) for several columns (1:6,26). It also gives the mean photon energy and intensity.

Returns:

The text.

Return type:

str

classmethod initialize_as_pencil(N=1000)

Creates a pencil beam (point source of zero divergence).

Parameters:

N (int, optional) – Number of rays.

Returns:

A pencil beam (zero cross section, zero divergence).

Return type:

S4Beam instance

classmethod initialize_from_array(array)

Creates an S4Beam instance from an array.

Parameters:

array (numpy array) – array to initialize the S4beam.

Return type:

an instance of S4Beam.

intensity(nolost=0)

Returns the intensity of the beam.

Parameters:

nolost (int, optional) –

• 0=use all rays,

• 1=use only good rays (non-lost rays),

• 2=use only lost rays.

Returns:

total intensity.

Return type:

float

is_cleaned()

Tells if the lost rays of the beam have been cleaned using S4Beam.clean_lost_rays().

Returns:

True if beam has been cleaned, else False.

Return type:

Boolean

isnan(verbose=1)

Informs on the existence of nan and returns the number of rays with nan.

Parameters:

verbose (int, optional) –

• 0=No,

• 1=verbose output.

Returns:

(N1_all, N1_good) the number of rays with nan in all rays (N1_all) and in good rays (N1_good).

Return type:

tuple

classmethod load_h5(filename, simulation_name='run001', beam_name='begin')

Loads a beam from an h5 file.

Parameters:

• filename (str) – file name.

• simulation_name (str, optional) – a simulation name,

• beam_name (str, optional) – a beam name.

Returns:

The beam

Return type:

S4beam instance

property rays_bad

Returns a numpy array with the bad rays.

Returns:

The bad rays.

Return type:

numpy array (nbadrays,18)

property rays_good

Returns a numpy array with the good rays.

Returns:

The good rays.

Return type:

numpy array (ngoodrays,18)

retrace(dist, resetY=False)

Propagates a beam at a given distance (in vacuum).

Parameters:

• dist (float) – The distance to be re-traced.

• resetY (boolean, optional) – If True, reset all Y values to zero (which physically is like calculating the beam intersections with a plane perpendicular to the optical axis)

rot_back(OFFX=0, OFFY=0, OFFZ=0, X_ROT=0, Y_ROT=0, Z_ROT=0)

Applies the roto-translation of the optical movement movements to the beam. This will bring back the beam in the normal optical-element frame.

Parameters:

• OFFX (float) – translation distance in m along the X axis.

• OFFY (float) – translation distance in m along the Y axis.

• OFFZ (float) – translation distance in m along the Z axis.

• X_ROT (float) – rotation angle in rad around the X axis.

• Y_ROT (float) – rotation angle in rad around the Y axis.

• Z_ROT (float) – rotation angle in rad around the Z axis.

rot_for(OFFX=0, OFFY=0, OFFZ=0, X_ROT=0, Y_ROT=0, Z_ROT=0)

Applies the roto-translation of the optical movement movements to the beam.

Parameters:

• OFFX (float) – translation distance in m along the X axis.

• OFFY (float) – translation distance in m along the Y axis.

• OFFZ (float) – translation distance in m along the Z axis.

• X_ROT (float) – rotation angle in rad around the X axis.

• Y_ROT (float) – rotation angle in rad around the Y axis.

• Z_ROT (float) – rotation angle in rad around the Z axis.

rotate(theta, axis=1, rad=True)

Rotates a beam by a given angle along a given axis.

Parameters:

• theta (float) – the rotation angle radians (of degress if rad=False).

• axis (int) – The axis number (Shadow’s column) for the rotation (i.e, 1:x (default), 2:y, 3:z)

• rad (boolean, optional) – set False if theta is given in degrees.

set_column(column, value)

Sets a given array in a given column number.

Parameters:

• column (int) – The column number.

• value (numpy array (or a float or int scalar)) – The values to be set.

set_jones(J, e_S=None, e_P=None)

set_jones_components(j0, j1, e_S=None, e_P=None)

set_photon_energy_eV(energy_eV)

Sets photon energies from a given array.

Parameters:

value (numpy array (or a float or int scalar)) – The values of the photon energies in eV.

set_photon_wavelength(wavelength)

Sets photon wavelengths from a given array.

Parameters:

value (numpy array (or a float or int scalar)) – The values of the wavelengths in m.

trace_oe(oe_object, n, overwrite=True)

Modify rays to trace an optical element. This option mimics the obsolete “trace” in shadow3. It should not be used, only for compatibility purposes.

Parameters:

• oe_object (instance of a shadow4 optical element.) – Instance of a source class that implements the trace_beam() method.

• n (int) – The element number (not used here)

translation(qdist1)

Translates spatially a beam by a given vector.

Parameters:

qdist1 (3 elements list or tuple) – The distances to translate the X,Y and Z components.

write_h5(filename, overwrite=True, simulation_name='run001', beam_name='begin')

writes a beam in an h5 file.

Parameters:

• filename (str) – file name.

• overwrite (boolean, optional) – if True, overwrite existing file (if False, the beam is appended in the existing file).

• simulation_name (str, optional) – a simulation name,

• beam_name (str, optional) – a beam name.

Module contents