quvac.grid

Functions for creating spatial and temporal grids.

1. GridXYZ class that calculates the spatial grid and its Fourier counterpart.

2. Helper function setup_grids that automatically creates grids either dynamically or from given grid sizes.

Warning

The dynamic grid creation is experimental and should be used with caution. Especially, when testing on new physical problems, it is recommended to visualize participating Maxwell fields and check the grid sizes.

Note

Parts of dynamical grid creation for gaussian beams were initially implemented by Alexander Blinne (get_kmax_from_bw, get_xyz_size, get_t_size).

Classes

GridXYZ

Calculates spatial grid and its Fourier counterpart.

Functions

get_ek(theta, phi)	Calculate k-vector for given spherical angles theta and phi.
get_pol_basis(theta, phi)	Calculate polarization basis for given spherical angles theta and phi.
get_polarization_vector(theta, phi, beta)	Calculate polarization vector for given spherical angles theta and phi
gaussian_bandwidth(field_params)	Calculate the gaussian bandwidth.
dipole_bandwidth(field_params)	Calculate the dipole bandwidth.
get_bw(field_params)	Calculate the bandwidths for a given field type.
get_kmax_from_bw(field_params)	Calculate the maximum k-vector from bandwidth along each dimension
get_kmax_grid(field_params)	Calculate the maximum k-vector along each dimension for a given field type.
get_xyz_size(fields, box_size[, grid_res, ...])	Calculate necessary spatial resolution.
get_t_size(t_start, t_end, lam[, grid_res])	Calculate necessary temporal resolution.
get_max_duration(fields_params)
get_box_size(fields_params, grid_params)	Calculate the necessary box size for the spatial grid.
create_dynamic_grid(fields_params, grid_params)	Dynamically create grids from given laser parameters.
setup_grids(fields_params, grid_params)	Create spatial and temporal grids from given sizes or

Module Contents

class quvac.grid.GridXYZ(grid)

Calculates spatial grid and its Fourier counterpart.

Parameters:

grid (tuple of np.array) – A tuple containing three numpy arrays (x, y, z) representing the spatial grid for field discretization.

grid

The spatial grid for field discretization.

Type:

tuple of np.array

grid_shape

The shape of the grid.

Type:

tuple of int

xyz

The meshgrid of the spatial grid.

Type:

tuple of np.array

dxyz

The grid spacing in each dimension.

Type:

tuple of float

dV

The volume element of the grid.

Type:

float

kgrid

The k-space grid.

Type:

tuple of np.array

kgrid_shifted

The shifted k-space grid.

Type:

tuple of np.array

dkxkykz

The spacing in k-space for each dimension.

Type:

list of float

dVk

The volume element in k-space.

Type:

float

kmeshgrid

The meshgrid of the k-space grid.

Type:

tuple of np.array

kabs

The absolute value of the k-vectors.

Type:

np.array

e1x, e1y, e1z

The x, y, and z components of the first polarization vector.

Type:

np.array

e2x, e2y, e2z

The x, y, and z components of the second polarization vector.

Type:

np.array

get_k_grid()

Calculate the k-space grid and polarization vectors.

Return type:

None

quvac.grid.get_ek(theta, phi)

Calculate k-vector for given spherical angles theta and phi.

Parameters:

• theta (float) – The polar angle in radians.

• phi (float) – The azimuthal angle in radians.

Returns:

A 3-element array representing the k-vector.

Return type:

numpy.ndarray

quvac.grid.get_pol_basis(theta, phi)

Calculate polarization basis for given spherical angles theta and phi.

Parameters:

• theta (float) – The polar angle in radians.

• phi (float) – The azimuthal angle in radians.

Returns:

A tuple containing two 3-element arrays representing the polarization basis vectors e1 and e2.

Return type:

tuple of numpy.ndarray

quvac.grid.get_polarization_vector(theta, phi, beta)

Calculate polarization vector for given spherical angles theta and phi and polarization angle beta.

Parameters:

• theta (float) – The polar angle in radians.

• phi (float) – The azimuthal angle in radians.

• beta (float) – The polarization angle in radians.

Returns:

3-element array representing the polarization vector.

Return type:

numpy.ndarray

quvac.grid.gaussian_bandwidth(field_params)

Calculate the gaussian bandwidth.

Parameters:

field_params (dict) –

Dictionary containing the field parameters. Required keys are:

• taufloat

  Pulse duration.

• w0float, optional

  Beam waist. If ‘w0’ is not provided, ‘w0x’ and ‘w0y’ are used.

Returns:

A tuple containing the perpendicular and longitudinal bandwidths kbw_perp, kbw_long).

Return type:

tuple of float

Notes

The bandwidths are calculated from the Fourier transform of transverse and longitudinal Gaussian profiles:

• exp(-r**2/w0**2) -> exp(-w0**2*kperp**2/4) -> kperp_bw ~ 2*2/w0

• exp(-t**2/(tau/2)**2) -> exp(-tau**2*k**2/16) -> k_long ~ 2*4/(c*tau)

quvac.grid.dipole_bandwidth(field_params)

Calculate the dipole bandwidth.

Parameters:

field_params (dict) –

Dictionary containing the field parameters. Required keys are:

• lamfloat

  Wavelength of the pulse.

• taufloat

  Pulse duration.

Returns:

A tuple containing the perpendicular and longitudinal bandwidths (kbw_perp, kbw_long).

Return type:

tuple of float

Notes

The length scales are taken from: I. Gonoskov et al. “Dipole pulse theory: Maximizing the field amplitude from 4π focused laser pulses.” PRA 86.5 (2012): 053836.

l_para = 0.58 * lam

l_perp = 0.4 * lam

quvac.grid.get_bw(field_params)

Calculate the bandwidths for a given field type.

Parameters:

field_params (dict) – Dictionary containing the field parameters.

Returns:

A tuple containing the perpendicular and longitudinal bandwidths (kbw_perp, kbw_long).

Return type:

tuple of float

Raises:

NotImplementedError – If the field type is not supported.

quvac.grid.get_kmax_from_bw(field_params)

Calculate the maximum k-vector from bandwidth along each dimension for a given field.

Parameters:

field_params (dict) –

Dictionary containing the field parameters. Required keys are:

• lamfloat

  Wavelength of the pulse.

• taufloat

  Pulse duration.

• thetafloat

  Polar angle in degrees.

• phifloat

  Azimuthal angle in degrees.

Returns:

A 3-element array representing the maximum k-vector along each dimension.

Return type:

numpy.ndarray

Notes

The maximum k-vector is calculated based on the bandwidths derived from the field parameters.

quvac.grid.get_kmax_grid(field_params)

Calculate the maximum k-vector along each dimension for a given field type.

Parameters:

field_params (dict) – Dictionary containing the field parameters.

Returns:

A 3-element array representing the maximum k-vector along each dimension.

Return type:

numpy.ndarray

Raises:

NotImplementedError – If the field type is not supported.

quvac.grid.get_xyz_size(fields, box_size, grid_res=1, equal_resolution=False)

Calculate necessary spatial resolution.

Parameters:

• fields (dict or list of dict) – Parameters of participating fields.

• box_size (sequence of float) – Box size for 3 dimensions.

• grid_res (float, optional) – Controls the resolution (default is 1).

• equal_resolution (bool, optional) – Flag indicating if equal resolution in every dimension is needed (default is False).

Returns:

List containing the number of grid points along each dimension.

Return type:

list of int

quvac.grid.get_t_size(t_start, t_end, lam, grid_res=1)

Calculate necessary temporal resolution.

Parameters:

• t_start (float) – Start time.

• t_end (float) – End time.

• lam (float) – Wavelength.

• grid_res (float, optional) – Factor to scale the resolution (default is 1).

Returns:

Number of time steps.

Return type:

float

quvac.grid.get_max_duration(fields_params)

quvac.grid.get_box_size(fields_params, grid_params)

Calculate the necessary box size for the spatial grid.

Parameters:

• fields_params (list of dict) –

  Parameters of participating fields. Each dictionary should contain:

  • field_typestr

    Type of the field.

  • w0float, optional

    Beam waist for focused fields.

  • taufloat, optional

    Pulse duration.

• grid_params (dict) –

  Grid parameters. Required keys are:

  • transverse_factorfloat

    Factor to scale the transverse size.

  • longitudinal_factorfloat

    Factor to scale the longitudinal size.

Returns:

A tuple containing the transverse and longitudinal sizes.

Return type:

tuple of float

Notes

The box size is calculated based on the maximum beam waist and pulse duration among the fields, scaled by the transverse and longitudinal factors.

quvac.grid.create_dynamic_grid(fields_params, grid_params)

Dynamically create grids from given laser parameters. One should be careful with this option.

Parameters:

• fields_params (list of dict) – Parameters of participating fields.

• grid_params (dict) – Grid parameters.

Returns:

Updated grid parameters including calculated box size, number of spatial points, and number of temporal points.

Return type:

dict

quvac.grid.setup_grids(fields_params, grid_params)

Create spatial and temporal grids from given sizes or dynamically from field parameters (e.g., duration and waist size).

Parameters:

• fields_params (list of dict) –

  Parameters of participating fields. Each dictionary should contain:

  • field_typestr

    Type of the field.

  • lamfloat

    Wavelength of the pulse.

  • w0float, optional

    Beam waist for focused fields.

  • taufloat, optional

    Pulse duration.

• grid_params (dict) –

  Grid parameters. Required keys are:

  • modestr

    Mode of grid creation (‘dynamic’ or ‘static’).

  Keys for ‘static’ mode:

  • box_xyztuple of float

    Box size for the spatial grid.

  • Nxyztuple of int

    Number of grid points along each spatial dimension.

  • Ntint

    Number of temporal points.

  • box_tfloat or tuple of float

    Time duration or start and end times for the temporal grid.

  Keys for ‘dynamic’ mode:

  • collision_geometrystr

    Specifies the collision geometry (‘x’, ‘y’, ‘z’).

  • transverse_factorfloat

    Factor to scale the transverse size.

  • longitudinal_factorfloat

    Factor to scale the longitudinal size.

  • time_factorfloat

    Factor to scale the time duration.

  • spatial_resolutionfloat or list of float, optional

    Controls the spatial resolution.

  • time_resolutionfloat, optional

    Controls the temporal resolution.

  • ignore_idxlist of int, optional

    Indices of fields to ignore for dynamic grid creation.

Returns:

A tuple containing:

• grid_xyzquvac.grid.GridXYZ

  The spatial grid object.

• grid_tnumpy.ndarray

  The temporal grid array.

Return type:

tuple

Notes

The spatial and temporal grids are created based on the mode specified in the grid parameters. If ‘dynamic’ mode is selected, the grids are created dynamically based on the field parameters.