Class pypfc_base

Bases: setup_grid
Methods:¶
__init__ ¶
Initialize the base PFC setup with domain parameters and device configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
domain_size
|
ndarray of float, shape (3,)
|
Physical size of the simulation domain [Lx, Ly, Lz] in lattice parameter units. |
required |
ndiv
|
ndarray of int, shape (3,)
|
Number of grid divisions [nx, ny, nz]. Must be even numbers for FFT compatibility. |
required |
config
|
dict
|
Configuration parameters as key-value pairs. See the pyPFC overview for a complete list of the configuration parameters. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If dtype_gpu is not torch.float32 or torch.float64. |
ValueError
|
If GPU is requested but no GPU is available. |
evaluate_C2_d ¶
Establish the two-point correlation function for a crystal structure.
Computes the two-point pair correlation function in Fourier space for the specified crystal structure using Gaussian peaks at reciprocal lattice positions.
Returns:
| Name | Type | Description |
|---|---|---|
C2_d |
(Tensor, shape(nx, ny, nz // 2 + 1))
|
Two-point pair correlation function on the computational device. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If C20_alpha is negative when C20_amplitude is non-zero. |
evaluate_directional_correlation_kernel ¶
Establish directional correlation kernel for a crystal structure.
Computes directional correlation kernels used in extended PFC models to introduce orientational dependence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
H0
|
float
|
Constant modulation of the peak height. |
required |
Rot
|
ndarray of float, shape (3, 3) or None
|
Lattice rotation matrix. If None, uses identity matrix. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
H_d |
(Tensor, shape(nx, ny, nz // 2 + 1))
|
Directional correlation kernel on the computational device. |
evaluate_k2_d ¶
Evaluate the sum of squared wave vectors for FFT operations.
Computes \(k^2 = k_x^2 + k_y^2 + k_z^2\) on the computational device using PyTorch FFT frequency grids. This is fundamental for Fourier-space operations in PFC simulations.
Returns:
| Name | Type | Description |
|---|---|---|
k2_d |
(Tensor, shape(nx, ny, nz_half))
|
Sum of squared wave vectors on the device. The z-dimension is reduced due to real FFT symmetry (nz_half = nz//2 + 1). |
evaluate_reciprocal_planes ¶
Establish reciprocal vectors/planes for a crystal structure.
Computes reciprocal lattice plane spacing (d-spacing) and wave vectors for crystallographic planes. For cubic systems: d = a / sqrt(h² + k² + l²) where a is the lattice parameter, and reciprocal spacing is k = 2π/d.
Returns:
| Name | Type | Description |
|---|---|---|
k_plane |
ndarray of float
|
Reciprocal lattice plane spacings (wave vector magnitudes). |
n_plane |
ndarray of int
|
Number of symmetrical planes in each family. |
den_plane |
ndarray of float
|
Atomic density within each plane family. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the crystal structure is not supported. |
ValueError
|
If there are not enough peaks defined for the requested number of peaks. |
Notes
For any family of lattice planes separated by distance d, there are reciprocal lattice points at intervals of 2π/d in reciprocal space.
expand_minimum_domain ¶
expand_minimum_domain(
min_domain_size: ndarray,
min_ndiv: ndarray,
target_domain_size: ndarray,
) -> Tuple[np.ndarray, np.ndarray]
Repeat a minimum domain size, required for 3D periodicity, to match a target domain size.
The returned grid parameters are adjusted to provide the closest possible match to the target domain size, without being smaller.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_domain_size
|
ndarray of float, shape (3,)
|
Minimum periodic domain size in each direction (e.g. output from
|
required |
min_ndiv
|
ndarray of int, shape (3,)
|
Minimum number of grid divisions for |
required |
target_domain_size
|
ndarray of float, shape (3,)
|
Desired domain size in each direction. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
domain_size_exp |
ndarray of float, shape (3,)
|
Adjusted domain size in each direction. |
ndiv_exp |
ndarray of int, shape (3,)
|
Adjusted number of grid divisions in each direction. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If input shapes are invalid, if any target domain component is non-positive, or if any minimum domain/grid component is non-positive. |
get_alpha ¶
Get the Gaussian peak widths for the two-point correlation function.
Returns:
| Name | Type | Description |
|---|---|---|
alpha |
ndarray of float
|
Gaussian peak widths (α_i) for each peak in the correlation function. |
get_atom_bond_data ¶
Evaluate min/max neighbor bond angles and bond lengths for each atom in a set of atoms.
The neighbor search is performed with periodic boundary conditions in all three directions using the simulation domain size.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
atom_coord
|
ndarray of float, shape (n_atoms, 3)
|
Coordinates of the atoms. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bond_angles |
ndarray of float, shape (2, n_atoms)
|
Min/Max neighbor bond angles for each atom. |
bond_lengths |
ndarray of float, shape (2, n_atoms)
|
Min/Max neighbor bond lengths for each atom. |
get_csl_config ¶
get_csl_config(
axis: Union[List[int], ndarray],
max_csl: int,
struct: str = "FCC",
gb_type: str = "tilt",
) -> List[Dict[str, Any]]
Generate candidate CSL configurations for symmetric tilt or twist grain boundaries.
The returned list contains candidate misorientation angles and associated
GB normals [u v w] for a specified GB axis [h k l]. The list can be used to pick
a commensurate angle and then call minimum_periodic_domain with
angle = theta/2.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axis
|
array_like of int, shape (3,)
|
Boundary-defining axis |
required |
max_csl
|
int
|
Maximum CSL number (Sigma) to include. |
required |
struct
|
str
|
Crystal structure. Options: 'FCC', 'BCC', 'SC'. |
'FCC'
|
gb_type
|
str
|
Type of grain boundary. Options: 'tilt', 'twist'. Default is 'tilt'. |
'tilt'
|
Returns:
| Name | Type | Description |
|---|---|---|
csl_list |
list of dict
|
Each item contains: - 'theta' (radians) - 'theta_deg' (degrees) - 'gb_normal' (list [u, v, w]) - 'csl' (Sigma) - 'pair' (integer generator pair (m, n)) - 'axis' (list [h, k, l]) - 'gb_type' ('tilt' or 'twist') |
get_csp ¶
Calculate the centro-symmetry parameter (CSP) for atoms.
Computes CSP values for atoms in a 3D periodic domain to identify crystal defects and disorder. CSP quantifies deviation from centro-symmetric local environments.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pos
|
ndarray of float, shape (natoms, 3)
|
3D coordinates of atoms. |
required |
normalize_csp
|
bool
|
If True, normalizes CSP values to range [0,1]. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
csp |
ndarray of float, shape (natoms,)
|
Centro-symmetry parameter for each atom. |
References
C.L. Kelchner, S.J. Plimpton and J.C. Hamilton, Dislocation nucleation and defect structure during surface indentation, Phys. Rev. B, 58(17):11085-11088, 1998. https://doi.org/10.1103/PhysRevB.58.11085
get_device_number ¶
Get the current GPU device number.
Returns:
| Type | Description |
|---|---|
int
|
Current GPU device index. |
get_device_type ¶
Get the current computation device type.
Returns:
| Type | Description |
|---|---|
str
|
Current device type ('CPU' or 'GPU'). |
get_dtype_cpu ¶
Get the current CPU data type.
Returns:
| Type | Description |
|---|---|
dtype
|
Current NumPy data type used for CPU arrays. |
get_dtype_gpu ¶
Get the current GPU data type.
Returns:
| Type | Description |
|---|---|
dtype
|
Current PyTorch data type used for GPU tensors. |
get_field_average_along_axis ¶
Evaluate the mean value of a field variable along a specified axis.
Computes the spatial average of a 3D field along one axis, reducing the dimensionality by averaging over the other two axes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field
|
ndarray of float, shape (nx, ny, nz)
|
3D field variable to be averaged. |
required |
axis
|
str
|
Axis to average along: x, y or z (case insensitive). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
result |
ndarray of float
|
1D array containing mean values along the specified axis. Shape depends on the axis: (nx,), (ny,), or (nz,). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If axis is not x, y or z. |
get_integrated_field_along_axis ¶
Integrate a field variable along a specified axis.
Performs numerical integration of a 3D field variable along one axis, integrating over the two orthogonal directions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field
|
ndarray of float, shape (nx, ny, nz)
|
3D field variable to be integrated. |
required |
axis
|
str
|
Axis to integrate along: x, y or z (case insensitive). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
result |
ndarray of float
|
1D array containing integrated values along the specified axis. Shape depends on the axis: (nx,), (ny,), or (nz,). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If axis is not x, y or z. |
get_integrated_field_in_volume ¶
Integrate a field variable within a defined volume.
Performs numerical integration of a field variable over a specified 3D volume on a Cartesian grid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field
|
ndarray of float, shape (nx, ny, nz)
|
Field to be integrated over the specified volume. |
required |
limits
|
array_like of float, length 6
|
Spatial integration limits: [xmin, xmax, ymin, ymax, zmin, zmax]. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
result |
float
|
Result of the volume integration. |
get_k ¶
Define a 1D wave vector for Fourier space operations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
npoints
|
int
|
Number of grid points. Must be even. |
required |
dspacing
|
float
|
Grid spacing in real space. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
k |
ndarray of float
|
1D wave vector array with proper frequency ordering for FFTs. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If npoints is not an even number. |
get_k2_d ¶
Get the wave vector magnitude squared tensor.
Returns:
| Type | Description |
|---|---|
Tensor
|
Wave vector magnitude squared (k²) tensor in Fourier space. |
get_phase_field_contour ¶
get_phase_field_contour(
pf: Union[ndarray, Tensor],
pf_zoom: float = 1.0,
evaluate_volume: bool = True,
) -> Union[Tuple[np.ndarray, float], np.ndarray]
Find the iso-contour surface of a 3D phase field using marching cubes.
Extracts iso-surfaces from 3D phase field data using the marching cubes algorithm, with optional volume calculation for enclosed regions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pf
|
ndarray of float, shape (nx, ny, nz)
|
3D phase field data for iso-surface extraction. |
required |
pf_zoom
|
float
|
Zoom factor for spatial coarsening/refinement. |
1.0
|
evaluate_volume
|
bool
|
If True, calculates the volume enclosed by the iso-surface. |
True
|
Returns:
| Name | Type | Description |
|---|---|---|
verts |
ndarray of float, shape (n_vertices, 3)
|
Vertices of the iso-surface triangulation. |
faces |
ndarray of int, shape (n_faces, 3)
|
Surface triangulation topology (vertex indices). |
volume |
(float, optional)
|
Volume enclosed by the iso-surface (only if evaluate_volume=True). |
get_rlv ¶
Get the reciprocal lattice vectors for a crystal structure.
Computes reciprocal lattice vectors for common crystal structures used in phase field crystal modeling.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
struct
|
str
|
Crystal structure type. Options: 'SC', 'BCC', 'FCC', 'DC'. |
required |
alat
|
float
|
Lattice parameter. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
rlv |
ndarray of float, shape (nrlv, 3)
|
Reciprocal lattice vectors for the specified crystal structure. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the crystal structure is not supported. |
get_time_stamp ¶
Get current timestamp string.
Returns:
| Name | Type | Description |
|---|---|---|
timestamp |
str
|
Current date and time in format: YYYY-MM-DD HH:MM. |
get_torch_threads ¶
Get the current PyTorch thread configuration.
Returns:
| Type | Description |
|---|---|
tuple of int
|
(num_threads, num_interop_threads) for PyTorch operations. |
get_verbose ¶
Get the current verbose output setting.
Returns:
| Type | Description |
|---|---|
bool
|
Current verbose mode setting. |
get_xtal_nearest_neighbors ¶
Get nearest neighbor information for crystal structures.
Computes nearest neighbor distances and coordination numbers for common crystal structures used in phase field crystal modeling.
Returns:
| Name | Type | Description |
|---|---|---|
nnb |
ndarray of int
|
Number of nearest and next-nearest neighbors. |
nnb_dist |
ndarray of float
|
Distances to the nearest and next-nearest neighbors. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the crystal structure is not supported. |
interpolate_atoms ¶
interpolate_atoms(
intrp_pos: ndarray,
pos: ndarray,
values: ndarray,
num_nnb: int = 8,
power: int = 2,
) -> np.ndarray
Interpolate values at given positions using inverse distance weighting.
Performs 3D interpolation in a periodic domain using inverse distance weighting: interpolated_value = Σ(wi × vi) / Σ(wi), where wi = 1 / (di^power).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
intrp_pos
|
ndarray of float, shape (n_intrp, 3)
|
3D coordinates of positions where values should be interpolated. |
required |
pos
|
ndarray of float, shape (n_particles, 3)
|
3D coordinates of particles with known values. |
required |
values
|
ndarray of float, shape (n_particles,)
|
Values at the particle positions to be interpolated. |
required |
num_nnb
|
int
|
Number of nearest neighbors to use for interpolation. |
8
|
power
|
float
|
Power for inverse distance weighting. |
2
|
Returns:
| Name | Type | Description |
|---|---|---|
interp_val |
ndarray of float, shape (n_intrp,)
|
Interpolated values at the specified positions. |
interpolate_density_maxima ¶
interpolate_density_maxima(
den: Union[ndarray, Tensor],
ene: Optional[Union[ndarray, Tensor]] = None,
fields: Optional[Union[ndarray, Tensor]] = None,
) -> Tuple[
np.ndarray, Optional[np.ndarray], Optional[np.ndarray]
]
Find density field maxima and interpolate atomic positions and properties.
Identifies local maxima in the density field as atomic positions and performs high-order interpolation to obtain sub-grid precision coordinates. Also interpolates associated field values at the atomic positions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
den
|
ndarray of float, shape (nx,ny,nz)
|
Density field from PFC simulation. |
required |
ene
|
ndarray of float, shape (nx,ny,nz)
|
Energy field for interpolation at atomic positions. |
None
|
fields
|
list of ndarray
|
List of additional fields for interpolation at atomic positions. Each array should have shape (nx,ny,nz). |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
atom_coord |
ndarray of float, shape (n_maxima,3)
|
Interpolated coordinates of density maxima (atomic positions). |
atom_data |
ndarray of float, shape (n_maxima, 2+n_phase_fields)
|
Interpolated field values at atomic positions. Columns: [density, energy, field1, field2, ..., fieldN] |
Notes
The method uses scipy.ndimage for high-order interpolation and applies
density thresholding and merging of nearby maxima to remove spurious peaks.
The interpolation order is controlled by the _density_interp_order attribute.
interpolate_gb_from_phase_field ¶
interpolate_gb_from_phase_field(
pf: Union[ndarray, Tensor], search_direction: str = "x"
) -> np.ndarray
Interpolate grain-boundary points from a phase-field iso-contour.
The GB position is defined as the first crossing of the iso-level
pf_iso_level along the selected search direction. The search
is periodic along the sweep axis, so the segment connecting the last and
first grid point is also considered.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pf
|
ndarray of float, shape (nx, ny, nz)
|
3D phase field data for GB interpolation. |
required |
search_direction
|
str
|
Direction along which to search for the GB. Options: 'x', '-x', 'y', '-y', 'z', '-z'. |
'x'
|
Returns:
| Name | Type | Description |
|---|---|---|
gb_point_coords |
ndarray of float, shape (n_points, 3)
|
Coordinates of grain-boundary points. For each line in the plane perpendicular to the search axis, one point is returned. If no crossing is found for a line, the coordinate in the search axis is NaN. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If search direction or phase-field shape is invalid. |
minimum_periodic_domain_bicrystal ¶
minimum_periodic_domain_bicrystal(
axis: ndarray,
angle: float,
alat: float = 1.0,
struct: str = "FCC",
target_ddiv: float = 0.125,
gb_type: str = "tilt",
) -> Tuple[
np.ndarray,
np.ndarray,
np.ndarray,
np.ndarray,
np.ndarray,
]
Find the minimum periodic 3D domain for a given crystal structure and grain boundary configuration.
The function estimates the smallest axis-aligned domain that is periodic
after rotating a crystal by angle around the GB axis [h k l].
The returned grid divisions are chosen so the grid spacing in each direction
does not exceed target_ddiv and the divisions remain even.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
axis
|
ndarray of float, shape (3,)
|
Grain-boundary axis given by Miller indices |
required |
angle
|
float
|
Rotation angle in radians. |
required |
alat
|
float
|
Lattice parameter. Default is 1.0. |
1.0
|
struct
|
str
|
Crystal structure. Options: 'FCC', 'BCC', 'SC'. Default is 'FCC'. |
'FCC'
|
target_ddiv
|
float
|
Maximum allowed grid spacing. Default is 0.125. |
0.125
|
gb_type
|
str
|
Type of grain boundary. Options: 'tilt', 'twist'. Default is 'tilt'. |
'tilt'
|
Returns:
| Name | Type | Description |
|---|---|---|
min_domain_size |
ndarray of float, shape (3,)
|
Minimum periodic domain dimensions. |
min_ndiv |
ndarray of int, shape (3,)
|
Minimum number of divisions for the periodic domain. |
ddiv |
ndarray of float, shape (3,)
|
Actual grid spacing in each direction, which does not exceed |
g1 |
ndarray of float, shape (3, 3)
|
Rotation matrix for crystal 1, rotated by |
g2 |
ndarray of float, shape (3, 3)
|
Rotation matrix for crystal 2, rotated by |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the axis is invalid, the structure is unsupported, or a periodic domain cannot be determined. |
minimum_periodic_domain_single_crystal ¶
minimum_periodic_domain_single_crystal(
orientation: ndarray,
alat: float = 1.0,
struct: str = "FCC",
target_ddiv: float = 0.125,
) -> Tuple[np.ndarray, np.ndarray, np.ndarray]
Find the minimum periodic 3D domain for a single oriented crystal.
The function estimates the smallest axis-aligned domain that is periodic
for a crystal whose orientation is given by a rotation matrix.
The returned grid divisions are chosen so the grid spacing in each direction
does not exceed target_ddiv and the divisions remain even.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
orientation
|
ndarray of float, shape (3, 3)
|
Crystal orientation matrix that maps the crystal frame to the lab frame. This should be a proper rotation matrix (orthonormal with determinant +1). |
required |
alat
|
float
|
Lattice parameter. Default is 1.0. |
1.0
|
struct
|
str
|
Crystal structure. Options: 'FCC', 'BCC', 'SC'. Default is 'FCC'. |
'FCC'
|
target_ddiv
|
float
|
Maximum allowed grid spacing. Default is 0.125. |
0.125
|
Returns:
| Name | Type | Description |
|---|---|---|
min_domain_size |
ndarray of float, shape (3,)
|
Minimum periodic domain dimensions. |
min_ndiv |
ndarray of int, shape (3,)
|
Minimum number of divisions for the periodic domain. |
ddiv |
ndarray of float, shape (3,)
|
Actual grid spacing in each direction, which does not exceed |
Raises:
| Type | Description |
|---|---|
ValueError
|
If orientation is invalid, the structure is unsupported, or a periodic domain cannot be determined. |
rotation_map_vector_to_x ¶
Construct a rotation matrix A such that
A @ n = e_x,
where e_x = [1, 0, 0].
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
ndarray of float, shape (3,)
|
Vector to be rotated to align with the x-axis. |
required |
eps
|
float
|
Tolerance for numerical comparisons (default is 1.0e-14). |
1e-14
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
ndarray of float, shape (3, 3)
|
Rotation matrix such that A @ n = e_x. |
set_alpha ¶
Set the Gaussian peak widths for the two-point correlation function.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
alpha
|
array_like of float
|
Gaussian peak widths (α_i) for each peak in the correlation function. |
required |
set_device_number ¶
Set the GPU device number for multi-GPU systems.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_number
|
int
|
GPU device index (0, 1, 2, ...) for CUDA computations. |
required |
set_device_type ¶
Set the computation device type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_type
|
str
|
Device type for computations. Options: 'CPU', 'GPU'. |
required |
set_dtype_cpu ¶
Set the CPU data type for numpy arrays.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
dtype
|
NumPy data type for CPU computations (e.g., np.float32, np.float64). |
required |
set_dtype_gpu ¶
Set the GPU data type for PyTorch tensors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
dtype
|
PyTorch data type for GPU computations (e.g., torch.float32, torch.float64). |
required |
set_k2_d ¶
Set the wave vector magnitude squared tensor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
k2_d
|
Tensor
|
Wave vector magnitude squared (k²) tensor in Fourier space. Used for FFT-based operations and differential operators. |
required |
set_torch_threads ¶
Set PyTorch thread configuration for CPU operations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nthreads
|
int
|
Number of threads for intra-op parallelism. |
required |
nthreads_interop
|
int
|
Number of threads for inter-op parallelism. |
required |
set_verbose ¶
Set verbose output mode for debugging and monitoring.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verbose
|
bool
|
If True, enables detailed timing and progress output. |
required |