qimpy.transport.material.ab_initio.AbInitio

class AbInitio(*, file, T, mu=0.0, rotation=None, orbital_zeeman=None, B=None, observable_names='n', relaxation_time=None, lindblad=None, light=None, emField=None, pulseB=None, process_grid, checkpoint_in=(None, ''))

Bases: Material

Ab initio material specification.

Parameters:

• file (str)

• T (float)

• mu (float)

• rotation (Tensor | None)

• orbital_zeeman (Optional[bool])

• B (Tensor | None)

• observable_names (list[str])

• relaxation_time (RelaxationTime)

• lindblad (Lindblad)

• light (Light)

• emField (Optional[Union[EMField, dict]])

• pulseB (PulseB)

• process_grid (ProcessGrid)

• checkpoint_in (CheckpointPath)

__init__(*, file, T, mu=0.0, rotation=None, orbital_zeeman=None, B=None, observable_names='n', relaxation_time=None, lindblad=None, light=None, emField=None, pulseB=None, process_grid, checkpoint_in=(None, ''))

Initialize ab initio material.

Parameters:

• file (str) – [Input file] Name of HDF5 file to load materials data from.

• T (float) – [Input file] Temperature.

• mu (float) – [Input file] Chemical potential in equilbrium.

• rotation (Tensor | ndarray | float | Sequence[float] | None) – [Input file] 3 x 3 rotation matrix from material to simulation frame. If unspecified (default), no rotation is performed.

• orbital_zeeman (bool | None) – [Input file] Whether to include L matrix elements in Zeeman coupling. The default None amounts to using L if available in the data.

• relaxation_time (RelaxationTime | dict | None) – [Input file] Relaxation-time approximation to scattering. Multiple scattering types specified will all contirbute independently.

• lindblad (Lindblad | dict | None) – [Input file] Ab-initio lindblad scattering. Multiple scattering types specified will all contirbute independently.

• light (Light | dict | None) – [Input file] Light-matter interaction (coherent / Lindblad).

• pulseB (PulseB | dict | None) – [Input file] Magnetic field pulses.

• emField (EMField | dict | None) – [Input file] Electromagnetic fields.

• observable_names (str | list[str]) –

  [Input file] Control which observables will be output. Specify either as a list of names, or a comma-separated string. Supported variables:

  • n: number density

  • jx, jy: number flux components

  • Sx, Sy, Sz: spin density components

  • jx_Sx, jx_Sy, …: spin flux, where jx_Sy = Sy flux along x direction

  By default, only n (number density) is output.

• B (Tensor | ndarray | float | Sequence[float] | None)

• process_grid (ProcessGrid)

• checkpoint_in (CheckpointPath)

Methods

__init__	Initialize ab initio material.
add_child	Construct child object self.`attr_name` of type cls.
add_child_one_of	Invoke add_child on one of several child options in args.
apply_evecs	Apply transformation by evecs to final two band dimensions.
get_contactor	Return a function (or callable object) to calculate the distribution function at a contact with orientation n and specified keyword arguments.
get_observable_names	Return list of observable names, specific to each material.
get_observables	Return tensor of complex conjugates of all observables specific to each material.
get_reflector	Return a function (or callable object) to calculate reflections for a sequence of surface points with unit normals (Nsurf x 2).
initialize	Initialize shared material parameters (call from a derived class.)
initialize_fields	Initialize spatially-dependent / parameter sweep values.
initialize_fields_local
measure_observables	Return expectation value of observables, (Nx x Ny x No).
read_scalars	Read quantities that don't transform with rotations from data_file.
read_vectors	Read quantities that transform as a vector with rotations from data_file.
read_vectors_attr	Read quantities that transform as a vector with rotations from data_file (stored as attribute).
rho_dot	Overall drho/dt in interaction picture.
rho_fermi	Compute the equilibrium density matrix corresponding to H.
save_checkpoint	Save self and all children in hierarchy to cp_path.
schrodingerV	Compute unitary rotations from interaction to Schrodinger picture.
zeemanH	Get Zeeman Hamiltonian due to specified external magnetic fields.

Attributes

transport_velocity	Effective velocity for each density-matrix component.
T
mu
rotation
P	Momentum matrix elements
S	Spin matrix elements
L	Angular momentum matrix elements
R	yet to be added)
B	Constant applied external field
evecs	Unitary rotations w.r.t data due to B, if any
lindblad	ab-initio Lindblad scattering
relaxation_time	semi-empirical relaxation time scattering
light	light-matter interactions
pulseB	magnetic field pulses
observables	Observable matrix elements in Schrodinger picture
observable_names	list of observable names to be output
dynamics_terms	all active drho/dt contributions
comm	Communicator for reciprocal-space split over k
k_division	Division of k-points over MPI
k_mine	slice of k on current process
nk_mine	number of k-points on current process
n_bands	number of bands at each k
n_dim	dimensionality of material (2 or 3)
wk	Brillouin zone integration weight
k	nk_mine x n_dim wave vectors
E	nk_mine x n_bands energies
v	nk_mine x n_bands x n_dim velocities in plane
rho0	nk_mine x n_bands x n_bands initial density matrix
dt_max	maximum stable time-step (set to inf if not available)
child_names	Names of attributes with child objects.
variant_name	Version of children having variants (if any)

apply_evecs(M)

Apply transformation by evecs to final two band dimensions. For convenience, handles optional tensors = None correctly.

Parameters:

M (Tensor | None)

Return type:

None

get_contactor(n, **kwargs)

Return a function (or callable object) to calculate the distribution function at a contact with orientation n and specified keyword arguments. For an Nsurf x 2 tensor n, the function should take time t as an input and return the corresponding Nsurf x Nkbb_mine distribution function.

Parameters:

n (Tensor)

Return type:

Callable[[float], Tensor]

get_observable_names()

Return list of observable names, specific to each material.

Return type:

list[str]

get_observables(t)

Return tensor of complex conjugates of all observables specific to each material. (No x Nkbb_mine) where No is number of observables.

Parameters:

t (float)

Return type:

Tensor

get_reflector(n)

Return a function (or callable object) to calculate reflections for a sequence of surface points with unit normals (Nsurf x 2). This function will be called with a Nghost x Nsurf x Nkbb_mine tensor, and the reflection should be calculated pointwise in real-space with output of the same dimensions.

Parameters:

n (Tensor)

Return type:

Callable[[Tensor], Tensor]

initialize_fields(rho, params, patch_id)

Initialize spatially-dependent / parameter sweep values. Using named properties params, containing tensors that should broadcast with the grid dimensions, update the density matrix rho to be spatially varying if necessary and calculate any named fields for use during dynamics. Note that the cached quantities must be associated with patch_id, as there may be multiple spatial domains (patches) sharing the same material.

Parameters:

• rho (Tensor)

• params (dict[str, Tensor])

• patch_id (int)

Return type:

None

read_scalars(data_file, name)

Read quantities that don’t transform with rotations from data_file.

Parameters:

• data_file (Checkpoint)

• name (str)

Return type:

Tensor

read_vectors(data_file, name)

Read quantities that transform as a vector with rotations from data_file. The second index is assumed to be the Cartesian index.

Parameters:

• data_file (Checkpoint)

• name (str)

Return type:

Tensor

read_vectors_attr(data_file, name)

Read quantities that transform as a vector with rotations from data_file (stored as attribute). The second index is assumed to be the Cartesian index.

Parameters:

• data_file (Checkpoint)

• name (str)

Return type:

Tensor

rho_dot(rho, t, patch_id)

Overall drho/dt in interaction picture. Input and output rho are in packed (real) form.

Parameters:

• rho (Tensor)

• t (float)

• patch_id (int)

Return type:

Tensor

rho_fermi(H, mu)

Compute the equilibrium density matrix corresponding to H. Also return the energies and eigenvectors of H.

Parameters:

• H (Tensor)

• mu (float)

Return type:

tuple[Tensor, Tensor, Tensor]

schrodingerV(t)

Compute unitary rotations from interaction to Schrodinger picture.

Parameters:

t (float)

Return type:

Tensor

zeemanH(B)

Get Zeeman Hamiltonian due to specified external magnetic fields.

Parameters:

B (Tensor)

Return type:

Tensor

B: torch.Tensor | None

Constant applied external field

L: torch.Tensor | None

Angular momentum matrix elements

P: torch.Tensor

Momentum matrix elements

R: torch.Tensor | None

yet to be added)

Type:

Position matrix elements (TODO

S: torch.Tensor | None

Spin matrix elements

dynamics_terms: dict[str, DynamicsTerm]

all active drho/dt contributions

evecs: torch.Tensor | None

Unitary rotations w.r.t data due to B, if any

light: Light

light-matter interactions

lindblad: Lindblad

ab-initio Lindblad scattering

observable_names: list[str]

list of observable names to be output

observables: torch.Tensor

Observable matrix elements in Schrodinger picture

pulseB: PulseB

magnetic field pulses

relaxation_time: RelaxationTime

semi-empirical relaxation time scattering