phenom Module API

phenom.gaussian.complex_gaussian_beam(x, y, photon_energy, pulse_energy, sigma, div, theta_x=0, theta_y=0, x0=0, y0=0)

Analytical model for a complex gaussian source

Parameters:

• x – 1d horizontal coordinate [np.array]

• y – 1d vertical coordinates [np.array]

• i – on-axis beam intensity

• sig0 – waist fwhm

• sigma – fwhm @ a distance z from the source

• div – beam divergence

• theta_x – horizontal tilt wavevector

• theta_y – vertical tilt wavevector

• mu – horizontal shift

• y0 – vertical shift

• z0 – source position

phenom.gaussian.gaussian_1d(x, a, mu, sigma)

generate a gaussian envelope for modelling the integrated pulse_data

Parameters:

• x – dependent-axis, one-dimensional numpy array

• a – amplitude of the gaussian (float)

• mu – mu

• width – widht of gaussian beam

Returns:

one-dimensioanl caussian profile

Created on Wed Jun 14 16:10:23 2023

@author: twguest

phenom.io.load_hdf5(file, pulse_id)

function to read data from a hdf5 file to create a dictionary for each pulse in a source file

Parameters:

• file – source .h5 directory (str)

• pulse_id – sub-group within .h5 (str)

class phenom.mesh.Mesh(nx=512, ny=512, nt=10, dx=1, dy=1, dt=1, x=None, y=None, t=None)

Bases: object

Generalized Mesh class.

This class can be constructed via two methods: from single-value field definitions or from numpy arrays defining exact coordinates.

Parameters:

nxint, optional

Number of points in the x direction, by default 512.

nyint, optional

Number of points in the y direction, by default 512.

ntint, optional

Number of points in the t direction, by default 10.

dxfloat, optional

Sampling interval in the x direction, by default 1.

dyfloat, optional

Sampling interval in the y direction, by default 1.

dtfloat, optional

Sampling interval in the t direction, by default 1.

xnp.ndarray, optional

Array of x coordinates, by default None.

ynp.ndarray, optional

Array of y coordinates, by default None.

tnp.ndarray, optional

Array of t coordinates, by default None.

build_from_array()

Constructs a mesh object from linear-space variables.

check_axes_options(axes)

Checks the axis options for validity.

Parameters:

axesint or str

Axis to check.

Raises:

AssertionError

If the axis is not valid.

get_array(axes=0)

Returns the mesh in array form.

Parameters:

axesint or str, optional

Axis to retrieve the array for, by default 0.

Returns:

np.ndarray

Array of coordinates for the specified axis.

get_extent()

Returns wpg style extent with respect to the transverse axis.

Returns:

list

Extent of the mesh in the form [xMin, xMax, yMin, yMax].

get_sampling()

Returns the two or three dimensional sampling of the field.

Returns:

tuple

Sampling intervals in each dimension.

property meshgrid

Returns a 2D numpy style meshgrid of spatial coordinates.

Returns:

tuple of np.ndarray

Meshgrid arrays for the x and y coordinates.

sampling()

Returns and records the field sampling in each of the spatial dimensions.

Created on Sat Jun 10 20:01:09 2023

@author: twguest

class phenom.source.SASE_Source(x, y, t, photon_energy, pulse_energy, pulse_duration, bandwidth, sigma, div, x0, y0, t0, theta_x, theta_y, domain='freq')

Bases: Source

generate_pulses(sdir)

generate_sase_field(params)

class phenom.source.Source(**kwargs)

Bases: object

Base structure of phenom.source model

features:

• io

• execute

• parseing annd

execute(method, sdir)

a non-parallelised method of generating pulse wavefront files using a method files are saved in perscribed sdirs

Parameters:

• method – wavefront generating method that takes in process params as its input

• sdir – single save directory

### execture needs a check that process keys match requirements of method

get_process_parameters()

calculates set of individual pulse parameters from queue used to generate of processes from queue

TO-DO: this function is where pulse name in the source .h5 is determined

refresh_processes()

regeneerate processes list from stored args.

used to regenerate pulses given input rules

store_hdf5(sdir)

phenom.source.check_arg_types(args)

phenom.source.get_queue(args)

source models method of parsing input values to individual pulse values

phenom.source.init_metadata()

wrapper to create metadata during Source init

phenom.source.sase_pulse(x, y, t, photon_energy, pulse_energy, pulse_duration, bandwidth, sigma, div, x0, y0, t0, theta_x, theta_y, domain='freq')

SASE pulse model

Parameters:

• x – horizontal coordinates (np.ndarray)

• y – vertical coordinates (np.ndarray)

• photon_energy – photon energy in eV (float)

• pulse_energy – pulse energy in J (float)

• pulse_duration – pulse duration in seconds (float)

• bandwidth – pulse bandwidth as a fraction of photon energy (float)

• sigma – gaussian beam width (float)

• div – beam divergence (float)

• x0 – horizontal position jitter (float)

• y0 – vertical position jitter (float)

• t0 – temporal jitter (float)

• theta_x – horizontal pointing angle (float)

• theta_y – vertical pointing angle (float)

• domain – ‘time’ or ‘freq’, determines the output of sase spectrum

phenom.source.sort_arg_types(args, __type__)

parser utility: sorts function types + array length assertions

Parameters:

• args – arguments of the Source function

• __type__ – argument types

Returns N:

number of pulses to iterate over

Returns __set__:

dict of argument keys sorted by value type

phenom.spectrum.linear_SASE_spectrum(t, pulse_duration, photon_energy, bandwidth=0.0001, t0=0, norm=False, plot=False, output='freq')

Generate a single SASE pulse profile in the time and frequency domain.

Parameters:

• t – Time axis [s](np.ndarray)

• pulse_duration – FWHM value of the SASE pulse duration [s](float)

• photon_energy – Central energy of the pulse [eV](float)

• bandwidth – Energy bandwidth / relative of the pulse [unitless](float)

• t0 – Timing jitter (generally should be less than 2*sampling*bandwidth) [s](float)

• norm – Normalize intensity spectrum to 1 [default=False](bool)

• plot – Plot the outputs if True [default=False](bool)

• output – ‘time’ or ‘frequency’ spectrum

Returns:

Complex spectrum in time or frequency domain [default time/s](np.ndarray)

Created on Sat Jun 10 20:03:10 2023

@author: twguest

phenom.utils.complex_to_wpg(arr)

converter function to transform complex wavefield into wpg style electric field array

Parameters:

arr – complex wavefield array [x,y,t] (complex128 type)

Returns new_arr:

wpg style electric field array [nx,ny,nz,2] (float64)

phenom.utils.e2k(photon_energy)

Converts photon energy to freq. wavevector

Parameters:

photon_energy – photon energy in eV

Returns k:

wavevector (1/m)

phenom.utils.e2wav(photon_energy)

Converts photon energy to photon wavelength.

Parameters:

photon_energy – photon energy in eV

Returns:

photon wavelength in m

Created on Sat Jun 10 20:01:52 2023

@author: twguest

phenom.wavefront_tools.geometric_focus(fwhm, divergence)

calculate the focal length of a converging beam of size fwhm

approximation that we are viewing the beam far downstream of the beam waist

phenom.wavefront_tools.wavefront_tilt(x, y, theta_x, theta_y, photon_energy)

define a two-dimensional complex tilted plane-wave, tilted along transverse pointing vectors kx and ky

Parameters:

• mesh – [2,nx,ny] array of coordinates, first-axis corresponds to x and y axis,

• kx – horizontal pointing vector [-pi, pi]

• ky – vertical pointing vector [-pi, pi]

Created on Wed Jun 14 16:10:23 2023

All functions in this file require the install of WPG

@author: twguest

phenom.wpg.complex_to_wpg(arr)

converter function to transform complex wavefield into wpg style electric field array

Parameters:

arr – complex wavefield array [x,y,t] (complex128 type)

Returns new_arr:

wpg style electric field array [nx,ny,nz,2] (float64)

phenom.wpg.wpg_converter(save_loc, key)

Convert saved phenom pulse to wpg type pulse

Parameters:

• save_loc – location of source .h5 master file (str)

• key – pulse key - e.g. ‘pulse000’ (str)

Returns wfr:

wpg compatible wavefront file