SourceTerm

Included in QATK.Dynamics

class SourceTerm(temporal, spatial, spatial_integral=None, integration_sampling_points=None)

Represents a source term in the two-temperature model heat equations.

The source term models energy deposition into the electronic subsystem in the two temperature model, typically from external sources such as laser irradiation.

Parameters:

  • temporal (callable that takes time as input) – The temporal part of the source term.

  • spatial (callable that takes position as input or PhysicalQuantity with same shape as the grid.) – The spatial part of the source term.

  • spatial_integral (PhysicalQuantity of type energy) – The total energy of the source term. If provided, the spatial part will be normalized to ensure that the integral over space equals this total energy.

  • integration_sampling_points (int) – The number of sampling points per dimension to use for integrating the spatial part of the source term over each cell in the grid.

localSpatialSourceTerms()

Get the local spatial source terms for each cell in the grid.

Returns:

The local spatial source terms for each cell in the grid.

Return type:

PhysicalQuantity with units power per volume

spatial(X, Y, Z)

Evaluate the spatial source term at the given set of points.

Parameters:

  • X (numpy.ndarray) – X-coordinates as an array (e.g., from numpy.meshgrid).

  • Y (numpy.ndarray) – Y-coordinates as an array (e.g., from numpy.meshgrid).

  • Z (numpy.ndarray) – Z-coordinates as an array (e.g., from numpy.meshgrid).

Returns:

The spatial source term evaluated at all points.

Return type:

PhysicalQuantity with same shape as input arrays with unit energy/length**3

temporal(t)

Evaluate the temporal source term at time t.

Parameters:

t (PhysicalQuantity of type time) – The time at which to evaluate the temporal source term.

Returns:

The temporal source term at time t.

Return type:

PhysicalQuantity of type 1/time

uniqueString()

Return a unique string representing the state of the object.

value(t, cell_index=None)

Get the value of the source term at time t and for a specific cell (or for all cells).

Parameters:

  • t (PhysicalQuantity of type time) – The time at which to evaluate the source term.

  • cell_index (int or None) – The index of the cell for which to evaluate the source term. If this is None, the source term for all cells is returned.

Returns:

The value of the source term at time t and for the specified cell.

Return type:

PhysicalQuantity with units power per volume

Usage Examples

Below is an example of how to create a source term to be used with the TwoTemperatureModelHook. In this example, a spatial function is defined that represents a Gaussian distribution of energy centered in the simulation cell. The temporal function is defined to deposit all energy at the initial time step (t=0 fs). The source term is then created by combining the spatial and temporal functions.

mid_point = (
    numpy.array([lattice[0][0] / 2, lattice[1][1] / 2, lattice[2][2] / 2])
    * Angstrom
)
def spatial(x, y, z):
    r = (
        (x - mid_point[0]) ** 2
        + (y - mid_point[1]) ** 2
        + (z - mid_point[2]) ** 2
    )
    return numpy.exp(-r / (0.01 * Angstrom**2)) * eV / (Angstrom**3)

# This is a simple example of a temporal part of the source term, it only act at t=0 fs.
# I.e all energy is deposited at the start of the calculation.
def temporal(t):
    if t == 0 * fs:
        return 1.0 / fs
    else:
        return 0.0 / fs

# Set up the source term object using the spatial and temporal parts.
# The total source is spatial * temporal
source_term = SourceTerm(temporal, spatial)

Notes

The SourceTerm can be used to add energy to the electronic sub-system when using the TwoTemperatureModelHook. A SourceTerm is created by providing two functions: a temporal function and a spatial function. The total source term is given by the product of these two functions.

\[S(x, y, z, t) = g(t) * f(x, y, z)\]

where \(g(t)\) is the temporal function that defines how the source term varies with time and \(f(x, y, z)\) is the spatial function that defines how the source term is distributed in space.

The spatial function should take three arguments \((x, y, z)\) representing coordinates in space and return the energy density (energy / volume) at those points. The temporal function should take a single argument t representing time and return a rate with units of 1 / time.

Spatial Integration Over Grid Cells

Since the energy is added to the electronic sub-system, we need to figure out the contribution of the source term to each grid cell representing the electronic sub-system in the Two-Temperature model. During initialization, the source term’s spatial function is numerically integrated over each grid cell using multiple sampling points (as defined by the integration_sampling_points parameter). This ensures that we have:

  1. Energy Conservation: The total energy deposited remains constant regardless of grid resolution.

  2. Resolution-Dependent Shape: The spatial distribution becomes more accurate with finer grids.

For example, consider the source term defined above, which represents a Gaussian energy distribution. The figure below illustrates how this Gaussian function is integrated over grid cells of varying sizes.

With different grid resolutions:

  • Coarse grid (few cells): Each cell receives the integrated energy over its volume. The distribution appears blocky and may not capture the Gaussian shape well.

  • Fine grid (many cells): The cell-averaged values closely approximate the continuous Gaussian function, producing a smooth distribution.

  • Single cell: All energy is deposited into one cell, effectively creating a uniform source.

../../../_images/source_term_integration.png

Fig. 194 Illustration of how a Gaussian source term is integrated over grid cells with different resolutions. The top panel shows the continuous Gaussian function, while the lower panels show the cell-averaged energy density for 5, 10, and 20 cells. As the number of cells increases, the discretized distribution better approximates the continuous function while conserving total energy.

In each molecular dynamics step, the Two-Temperature Model algorithm evaluates the temporal function and multiplies it by the pre-computed cell-averaged spatial values, adding the resulting energy density to each cell in the electronic temperature grid.