femlabpy.periodic#

Periodic-boundary and homogenization utilities for unit-cell workflows.

Workflow role#

This module takes a mesh that already exists and turns it into a periodic analysis problem. It finds matching boundary nodes, builds the multi-point constraint system, applies macro strain terms, solves the constrained system, and computes volume-averaged stress or strain for homogenization studies.

Public entry points#

find_periodic_pairs and find_all_periodic_pairs identify matching nodes on opposing faces.
periodic_constraints and apply_macro_strain build the constraint equations and their right-hand side terms.
solve_periodic wraps the constrained solution path.
volume_average_stress, volume_average_strain, and homogenize provide the post-processing layer for effective-property calculations.

Functions#

`apply_macro_strain`(X, pairs, eps_macro, dof)	Compute the RHS vector Q for periodic BCs with imposed macro strain.
`check_periodic_mesh`(X, axis[, tol])	Validate that a mesh is periodic along a given axis.
`find_all_periodic_pairs`(X, periodic_axes[, tol])	Find periodic node pairs along multiple axes.
`find_periodic_pairs`(X, axis[, tol])	Match nodes on opposite faces of a domain along a given axis.
`fix_corner`(X, C_existing, dof)	Add zero-displacement constraints at the corner node to remove rigid body modes.
`homogenize`(K, T, X, G_mat, pairs, dof, *[, ...])	Compute the effective (homogenized) stiffness tensor of an RVE.
`periodic_constraints`(X, pairs, dof, *[, ...])	Build the constraint matrix G and RHS Q for periodic BCs.
`solve_periodic`(K, p, X, pairs, dof, *[, ...])	Solve a periodic boundary value problem using Lagrange multipliers.
`volume_average_strain`(T, X, G_mat, u, dof, *)	Compute volume-averaged strain over all elements.
`volume_average_stress`(T, X, G_mat, u, dof, *)	Compute volume-averaged stress over all elements.

Function Reference#

femlabpy.periodic.apply_macro_strain(X, pairs, eps_macro, dof: int)[source]#

Compute the RHS vector Q for periodic BCs with imposed macro strain.

Parameters:

Xarray_like: Nodal coordinates.
pairsndarray: Periodic node pairs (1-based).
eps_macroarray_like: Macro strain in Voigt form.
dofint: DOFs per node.

Returns:

Qndarray, shape (n_constraints, 1)

femlabpy.periodic.check_periodic_mesh(X, axis: int, tol: float = 1e-06) → dict[source]#

Validate that a mesh is periodic along a given axis.

Parameters:

Xarray_like: Nodal coordinates.
axisint: Axis to check.
tolfloat: Tolerance.

Returns:

reportdict: Keys: 'valid', 'n_left', 'n_right', 'max_mismatch', 'message'.

femlabpy.periodic.find_all_periodic_pairs(X, periodic_axes, tol: float = 1e-06) → dict[source]#

Find periodic node pairs along multiple axes.

Parameters:

Xarray_like, shape (nn, ndim): Nodal coordinates.
periodic_axeslist of int: Axes along which periodicity is enforced (e.g. [0, 1] for 2D).
tolfloat: Matching tolerance.

Returns:

dict: {axis: pairs_array} for each periodic axis.

femlabpy.periodic.find_periodic_pairs(X, axis: int, tol: float = 1e-06)[source]#

Match nodes on opposite faces of a domain along a given axis.

Parameters:

Xarray_like, shape (nn, ndim): Nodal coordinates.
axisint: Axis index (0=x, 1=y, 2=z) along which to identify periodicity.
tolfloat: Matching tolerance relative to domain size.

Returns:

pairsndarray, shape (n_pairs, 2): Each row [left_node, right_node] with 1-based node numbers.

femlabpy.periodic.fix_corner(X, C_existing, dof: int)[source]#

Add zero-displacement constraints at the corner node to remove rigid body modes.

Parameters:

Xarray_like: Nodal coordinates.
C_existingarray_like or None: Existing constraint table.
dofint: DOFs per node.

Returns:

C_extendedndarray: Extended constraint table.

femlabpy.periodic.homogenize(K, T, X, G_mat, pairs, dof: int, *, element_type: str = 'q4')[source]#

Compute the effective (homogenized) stiffness tensor of an RVE.

Applies canonical unit strains and extracts the effective constitutive matrix from volume-averaged stress-strain relationships.

Parameters:

Kndarray or sparse: Global stiffness matrix.
Tarray_like: Element topology.
Xarray_like: Nodal coordinates.
G_matarray_like: Material property table.
pairsndarray: Periodic node pairs.
dofint: DOFs per node.
element_typestr: 't3' or 'q4'.

Returns:

C_effndarray, shape (n_voigt, n_voigt): Effective stiffness matrix.

femlabpy.periodic.periodic_constraints(X, pairs, dof: int, *, eps_macro=None)[source]#

Build the constraint matrix G and RHS Q for periodic BCs.

Constraints: u_right - u_left = eps_macro * (x_right - x_left)

Parameters:

Xarray_like, shape (nn, ndim): Nodal coordinates.
pairsndarray, shape (n_pairs, 2): Node pairs (1-based): [[left, right], …].
dofint: DOFs per node.
eps_macroarray_like, optional: Macro strain tensor in Voigt notation: [exx, eyy, gxy] for 2D or [exx, eyy, ezz, gxy, gyz, gxz] for 3D. If None, purely periodic (zero fluctuation).

Returns:

Gndarray, shape (n_constraints, ndof_total): Constraint matrix.
Qndarray, shape (n_constraints, 1): Constraint RHS.

femlabpy.periodic.solve_periodic(K, p, X, pairs, dof: int, *, eps_macro=None, return_lagrange=False)[source]#

Solve a periodic boundary value problem using Lagrange multipliers.

Parameters:

Kndarray or sparse: Global stiffness matrix.
pndarray: Load vector.
Xarray_like: Nodal coordinates.
pairsndarray: Periodic node pairs (1-based).
dofint: DOFs per node.
eps_macroarray_like, optional: Imposed macro strain in Voigt form.
return_lagrangebool: If True, also return Lagrange multipliers.

Returns:

undarray, shape (ndof, 1): Displacement solution.
lamndarray (only if return_lagrange=True): Lagrange multiplier values.

femlabpy.periodic.volume_average_strain(T, X, G_mat, u, dof: int, *, element_type: str = 'q4')[source]#

Compute volume-averaged strain over all elements.

Parameters are the same as volume_average_stress.

Returns:

eps_avgndarray: Volume-averaged strain in Voigt notation.

femlabpy.periodic.volume_average_stress(T, X, G_mat, u, dof: int, *, element_type: str = 'q4')[source]#

Compute volume-averaged stress over all elements.

sigma_avg = (1/V_total) * sum(sigma_e * V_e)

Parameters:

Tarray_like: Element topology table.
Xarray_like: Nodal coordinates.
G_matarray_like: Material property table.
uarray_like: Displacement solution.
dofint: DOFs per node.
element_typestr: Element type: 't3', 'q4', 't4', 'h8'.

Returns:

sigma_avgndarray: Volume-averaged stress in Voigt notation.