shadow4.sources.undulator package

Submodules

shadow4.sources.undulator.calculate_undulator_emission module

Calculation of undulator far field and backpropagation to the center of the undulator Implementation using internal code (no dependency) hacked from pySRU for source simulation and Wofry2D for backpropagation.

Available public functions:

calculate_undulator_emission()

undul_cdf() [like undul_cdf in SHADOW3].

shadow4.sources.undulator.calculate_undulator_emission.calculate_undulator_emission(electron_energy=6.0, electron_current=0.2, undulator_period=0.018, undulator_nperiods=100, K=1.0, photon_energy=2000.0, EMAX=20000.0, NG_E=10, MAXANGLE=0.1, number_of_points=100, NG_P=100, number_of_trajectory_points=100, flag_size=2, distance=100.0, magnification=0.01, flag_backprop_recalculate_source=0, flag_backprop_weight=0, weight_ratio=0.5)[source]

Calculate undulator emission (far field) and backpropagation to the center of the undulator using internal code.

Parameters:

  • electron_energy (float, optional) – The electron energy in GeV.

  • electron_current (float, optional) – The electron beam current in A.

  • undulator_period (float, optional) – The undulator period in m.

  • undulator_nperiods (float, optional) – The undulator number of periods.

  • K (float, optional) – The undulator K factor (vertical).

  • photon_energy (float, optional) – The photon energy (or starting energy for arrays) in eV.

  • EMAX (float, optional) – The end photon energy (for arrays).

  • NG_E (int, optional) – The number of points in photon energy (>1 for array).

  • MAXANGLE (float, optional) – The maximum half-angle for delimiting the calculation in rad.

  • number_of_points (int, optional) – The number of points in theta (elevation angle) or x and y.

  • NG_P (int, optional) – The number of points in psi (azimuthal angle).

  • number_of_trajectory_points (int, optional) – The number of trajectory points (per period).

  • flag_size (int, optional) – A flag to control the model used for sampling the radiation size at the center of the undulator: 0=point, 1=Gaussian, 2=backpropagated the far field.

  • distance (float, optional) – The distance to place the image plane where far field is calculated in m.

  • magnification (float, optional) – The magnification for backpropagation.

  • flag_backprop_recalculate_source (int, optional) – for code_undul_phot in [“internal”, “pysru”] and flag_size=2: apply Gaussian weight to backprop amplitudes (0=No, 1=Yes).

  • flag_backprop_weight (int, optional) – for code_undul_phot in [“internal”, “pysru”] and flag_size=2: apply Gaussian weight to backprop amplitudes.

  • weight_ratio (float, optional) – for flag_backprop_weight=1: the Gaussian sigma in units of r.max().

Returns:

A dictionary with calculated values and arrays.

Return type:

dict

shadow4.sources.undulator.calculate_undulator_emission_pysru module

shadow4.sources.undulator.calculate_undulator_emission_srw module

Calculation of undulator far field and backpropagation to the center of the undulator SRW implementation

Available public functions:

calculate_undulator_emission_srw()

shadow4.sources.undulator.calculate_undulator_emission_srw.calculate_undulator_emission_srw(electron_energy=6.0, electron_current=0.2, undulator_period=0.018, undulator_nperiods=100, K=1.0, photon_energy=2000.0, EMAX=20000.0, NG_E=10, MAXANGLE=0.1, number_of_points=100, NG_P=100, number_of_trajectory_points=100, flag_size=2, distance=100.0, srw_range=0.05, srw_resolution=50.0, srw_semianalytical=0)[source]

Calculate undulator emission (far field) and backpropagation to the center of the undulator using srw.

Parameters:

  • electron_energy (float, optional) – The electron energy in GeV.

  • electron_current (float, optional) – The electron beam current in A.

  • undulator_period (float, optional) – The undulator period in m.

  • undulator_nperiods (float, optional) – The undulator number of periods.

  • K (float, optional) – The undulator K factor (vertical).

  • photon_energy (float, optional) – The photon energy (or starting energy for arrays) in eV.

  • EMAX (float, optional) – The end photon energy (for arrays).

  • NG_E (int, optional) – The number of points in photon energy (>1 for array).

  • MAXANGLE (float, optional) – The maximum half-angle for delimiting the calculation in rad.

  • number_of_points (int, optional) – The number of points in theta (elevation angle) or x and y.

  • NG_P (int, optional) – The number of points in psi (azimuthal angle).

  • number_of_trajectory_points (int, optional) – The number of trajectory points (per period).

  • flag_size (int, optional) – A flag to control the model used for sampling the radiation size at the center of the undulator: 0=point, 1=Gaussian, 2=backpropagated the far field.

  • distance (float, optional) – The distance to place the image plane where far field is calculated in m.

  • srw_range (float, optional) – The SRW range factor (affecting both the H and V directions).

  • srw_resolution (float, optional) – The SRW resolution factor (affecting both the H and V directions).

  • srw_semianalytical (int, optional) – A flag to indicate if SRW uses the semianalytical treatment of the phases (0=No, 1=Yes).

Returns:

A dictionary with calculated values and arrays.

Return type:

dict

shadow4.sources.undulator.s4_undulator module

S4 Undulator magnetic structure.

class shadow4.sources.undulator.s4_undulator.S4Undulator(K_vertical=1.0, period_length=0.01, number_of_periods=100, emin=10000.0, emax=11000.0, ng_e=11, maxangle=5e-05, ng_t=31, ng_p=21, ng_j=20, code_undul_phot='internal', flag_emittance=0, flag_size=0, distance=100, srw_range=0.05, srw_resolution=50.0, srw_semianalytical=0, magnification=0.01, flag_backprop_recalculate_source=0, flag_backprop_weight=0, weight_ratio=0.5, flag_energy_spread=0)[source]

Bases: Undulator

Defines a shadow4 undulator magnetic structure.

Parameters:

  • K_vertical (float, optional) – the K value.

  • period_length (float, optional) – for magnetic_field_periodic=1, the period in m.

  • number_of_periods (float, optional) – for magnetic_field_periodic=1, the number of periods.

  • emin (float, optional) – minimum photon energy in eV.

  • emax (float, optional) – maximum photon energy in eV.

  • ng_e (int, optional) – Number of points in energy. This is used for the calculation of the spectrum, and also for sampling rays if flag_interpolation=1.

  • maxangle (float, optional) – Maximum radiation semiaperture in RADIANS.

  • ng_t (int, optional) – the number of points for angle theta.

  • ng_p (int, optional) – the number of points for angle phi.

  • ng_j (int, optional) – Number of points PER PERIOD in calculating the electron trajectory.

  • code_undul_phot (str, optional) – code to be used for calculating the emission vs angle: internal, pysru, SRW

  • flag_emittance (int, optional) – Flag: 0=Zero emittance (filament beam), 1=Use emittance.

  • flag_size (int, optional) – Method used for sampling the source size: 0=point, 1=Gaussian, 2=Backpropagated far field.

  • use_gaussian_approximation (int, optional) – 0=No, 1=Yes.

  • srw_range (float, optional) – for code_undul_phot=”srw” the range factor.

  • srw_resolution (float, optional) – for code_undul_phot=”srw” the resolution factor.

  • srw_semianalytical (int, optional) – for code_undul_phot=”srw” flag to apply the semianalytical phase treatement (0=No, 1=Yes).

  • magnification (float, optional) – for code_undul_phot in [“internal”, “pysru”]: the magnification factor.

  • flag_backprop_recalculate_source (int, optional) – for code_undul_phot in [“internal”, “pysru”] and flag_size=2: apply Gaussian weight to backprop amplitudes (0=No, 1=Yes).

  • flag_backprop_weight (int, optional) – for code_undul_phot in [“internal”, “pysru”] and flag_size=2: apply Gaussian weight to backprop amplitudes.

  • weight_ratio (float, optional) – for flag_backprop_weight=1: the Gaussian sigma in units of r.max().

  • flag_energy_spread (int, optional) – Flag: 0=do not include energy spread effects, 1=do include energy spread effects (the value will be available from the electron beam).

get_energy_box()[source]

Returns the limits of photon energy distribution for the source and the number of points.

Returns:

(emin, emax, npoints)

Return type:

tuple

get_flag_emittance()[source]

Returns the flag for considering electron beam emittance.

Returns:

0=No, 1=Yes.

Return type:

int

get_info(debug=False)[source]

Returns the specific information for the undulator magnetic structure.

Return type:

str

get_number_of_energy_points()[source]

Returns the number of photon energy points.

Return type:

int

is_monochromatic()[source]

Returns a flag indicating if the source is monochromatic (True) or polychromatic (False).

Return type:

boolean

set_energy_box(emin, emax, npoints=None)[source]

Sets a box for photon energy distribution for the source.

Parameters:

  • emin (float) – minimum photon energy in eV.

  • emax (float) – maximum photon energy in eV.

  • npoints (int or None, optional) – Number of points in energy. If None, it does not modify the number of points already stored.

set_energy_monochromatic(emin)[source]

Sets a single energy line for the source (monochromatic).

Parameters:

emin (float) – photon energy in eV.

set_maxangle(maxangle)[source]

Defines the maximum angle (in rads) for radiation calculations.

Parameters:

maxangle (float) – The angle in rads.

to_python_code()[source]

Returns the python code for defining the wiggler magnetic structure.

Returns:

The python code.

Return type:

str

shadow4.sources.undulator.s4_undulator_gaussian module

S4 Undulator magnetic structure.

class shadow4.sources.undulator.s4_undulator_gaussian.S4UndulatorGaussian(period_length=0.01, number_of_periods=100, photon_energy=10000.0, delta_e=0.0, ng_e=11, flag_emittance=0, flag_energy_spread=0, harmonic_number=1, flag_autoset_flux_central_cone=0, flux_central_cone=10000000000.0)[source]

Bases: Undulator

Defines a shadow4 undulator magnetic structure.

Parameters:

  • K_vertical (float, optional) – the K value.

  • period_length (float, optional) – for magnetic_field_periodic=1, the period in m.

  • number_of_periods (float, optional) – for magnetic_field_periodic=1, the number of periods.

  • emin (float, optional) – minimum photon energy in eV.

  • emax (float, optional) – maximum photon energy in eV.

  • ng_e (int, optional) – Number of points in energy. This is used for the calculation of the spectrum, and also for sampling rays if flag_interpolation=1.

  • flag_emittance (int, optional) – Flag: 0=Zero emittance (filament beam), 1=Use emittance.

  • flag_energy_spread (int, optional) – Flag: 0=do not include energy spread effects, 1=do include energy spread effects (the value will be available from the electron beam).

  • harmonic_number (int, optional) – The harmonic in use (used if flag_energy_spread=1).

  • flag_autoset_flux_central_cone (int, optional) – Autocalculate the flux in central cone (to be used for calculating the spectrum).

  • flux_central_cone (float, optional) – The value of the flux in the central cone in photons/s/0.1%bw (overwritten if flag_autoset_flux_central_cone=1).

get_energy_box()[source]

Returns the limits of photon energy distribution for the source and the number of points.

Returns:

(photon_energy, delta_e, self._NG_E)

Return type:

tuple

get_flag_emittance()[source]

Returns the flag for considering electron beam emittance.

Returns:

0=No, 1=Yes.

Return type:

int

get_flag_energy_spread()[source]

Returns the flag for considering electron energy spread.

Returns:

0=No, 1=Yes.

Return type:

int

get_info()[source]

Returns the specific information of the undulator magnetic structure in Gaussian approximation.

Return type:

str

get_number_of_energy_points()[source]

Returns the number of photon energy points.

Return type:

int

is_monochromatic()[source]

Returns a flag indicating if the source is monochromatic (True) or polychromatic (False).

Return type:

boolean

set_energy_box(photon_energy, delta_e=0.0)[source]

Sets a box for photon energy distribution for the source.

Parameters:

  • photon_energy (float) – photon energy in eV.

  • delta_e (float, optional) – interval for photon energy in eV.

set_energy_monochromatic(photon_energy)[source]

Sets a single energy line for the source (monochromatic).

Parameters:

emin (float) – photon energy in eV.

to_python_code()[source]

Returns the python code for defining the wiggler magnetic structure.

Returns:

The python code.

Return type:

str

shadow4.sources.undulator.s4_undulator_gaussian_light_source module

Undulator light source.

Computes undulator radiation distributions and samples rays according to them.

The radiation divergences (far field) are computed in polar coordinates for a more efiicient sampling.

class shadow4.sources.undulator.s4_undulator_gaussian_light_source.S4UndulatorGaussianLightSource(name='Undefined', electron_beam=None, magnetic_structure=None, nrays=5000, seed=12345)[source]

Bases: S4LightSource

Defines an undulator light source and implements the mechanism of sampling rays.

Parameters:

  • name (str, optional) – The name of the light source.

  • electron_beam (instance of ElectronBeam) – The electron beam parameters.

  • magnetic_structure (instance of S4BendingMagnet) – The shadow4 bending magnet magnetic structure.

  • nrays (int, optional) – The number of rays.

  • seed (int, optional) – The Monte Carlo seed.

classmethod Fn(K, n)[source]

Calculate the universal function Fn(x).

Parameters:

  • K (float) – The K value

  • n (int, optional) – The harmonic number (it must be odd).

Returns:

Fn(x)

Return type:

float

References

see fig 2.4 in X-RAY DATA BOOKLET https://xdb.lbl.gov/

classmethod Qn(K, n)[source]

Calculate the universal function Qn(x).

Parameters:

  • K (float) – The K value

  • n (int, optional) – The harmonic number (it must be odd).

Returns:

Qn(x)

Return type:

float

References

see fig 2.6 in X-RAY DATA BOOKLET https://xdb.lbl.gov/

calculate_spectrum()[source]

Calculates the spectrum.

Returns:

(e, f, w) numpy arrays with photon energy (e) in eV, photon flux (f) in (photons/s/0.1%bw) and spectral power (w) in W/eV.

Return type:

tuple

get_beam()[source]

Creates the beam as emitted by the undulator.

Return type:

instance of S4Beam

get_flux()[source]

Return the integrated flux (photons/s/0.1%bw) versus photon energy.

Returns:

(flux, photon_energy).

Return type:

tuple

get_flux_central_cone(K=None)[source]

Calculate the flux in the central code.

Parameters:

K (float or None, optional) – If None, K is calculated for the photon energy and harmonic_number defined in S4UndulatorGaussian. Otherwise, use the value defined here.

Returns:

The flux in photons/s/0.1%bw.

Return type:

float

References

see pag 2.8 in X-RAY DATA BOOKLET https://xdb.lbl.gov/

get_info(debug=False)[source]

Returns the specific information for the Gaussian undulator light source.

Return type:

str

get_size_and_divergence_vs_photon_energy(Kmin=0, Kmax=5.0, max_harmonic_number=11)[source]

Calculates the photon source size and divergences. It makes a scan in photon energy and considers electron emittance and electron energy spread. It uses Gaussian approximation.

Parameters:

  • Kmin (float, optional) – The minimum value of K to be used.

  • Kmax (float, optional) – The maximum value of K to be used.

  • max_harmonic_number (int, optional) – The maximum harmonic to be consideres in the calculation (1,3,5,… max_harmonic_number).

Returns:

(Energies, SizeH, SizeV, DivergenceH, DivergenceV, Labels) arrays (n,m) n: harmonic index. n=0 means no energy spread considered. m is the number of energy points.

Return type:

tuple

get_spectral_power()[source]

Return the integrated spectral power (W/eV) versus photon energy.

Returns:

(spectral_power, photon_energy).

Return type:

tuple

classmethod get_undulator_photon_beam_sizes(undulator_E0=15000.0, undulator_length=4.0)[source]

Returns the filament beam undulator size and divergence at resonance using Gaussian approximation.

Parameters:

  • undulator_E0 (float, optional) – The undulator resonance energy in eV.

  • undulator_length (float, optional) – The undulator length in meters.

Returns:

(sigma, sigma’).

Return type:

tuple

References

Equations 25 & 30 Generalities on the synchrotron radiation, Pascal Elleaume in H. Onuki. P. Elleaume: “Undulators, Wigglers and their Applications Taylor & Francis, New York 2003.

norm_energ_spr(harmonic_number=None)[source]

Calculate the “normalized” electron energy spread: 2 pi * harmonic_number * n_periods * energy spread DE/E.

Parameters:

harmonic_number (int or None, optional) – the harmonic number to be used. If None, use the one define in S4GaussianUndulator, otherwise use the one defined here. It must be odd.

Returns:

The normalized energy spread.

Return type:

float

References

Equation 13 in Tanaka, T. & Kitamura, H. (2009). Journal of Synchrotron Radiation, 16(3), 380–386

classmethod q_a(x)[source]

Universal function Qa by Tanaka & Kitamura 2009 equation (17).

Parameters:

x (float) – The argument.

Returns:

Qa(x).

Return type:

float

References

Equation 17 in Tanaka, T. & Kitamura, H. (2009). Journal of Synchrotron Radiation, 16(3), 380–386

classmethod q_s(x, factor=1.0)[source]

Universal function Qs by Tanaka & Kitamura 2009 equation (24).

Parameters:

  • x (float) – The argument.

  • factor (float, optional) – A multiplicative factor (set to 0.5 to force Qs(0)=1 ).

Returns:

Qs(x).

Return type:

float

References

Equation 24 in Tanaka, T. & Kitamura, H. (2009). Journal of Synchrotron Radiation, 16(3), 380–386

classmethod theoretical_flux_integrated_central_cone(N=100.0, n=1.0, current=0.2, K=1.68)[source]

Calculate the theoretical flux in the central cone.

Parameters:

  • N (int, optional) – The number of periods of the undulator.

  • n (int, optional) – The harmonic number (it must be odd).

  • current (float, optional) – The storage ring electron current in A.

  • K (float, optional) – The K value

Returns:

The flux in photons/s/0.1%bw.

Return type:

float

References

see pag. 2.8 in X-RAY DATA BOOKLET https://xdb.lbl.gov/

to_python_code(**kwargs)[source]

Returns the python code for calculating the wiggler source.

Returns:

The python code.

Return type:

str

shadow4.sources.undulator.s4_undulator_light_source module

Module contents