matscipy.fracture_mechanics.continuation

Force-only pseudo-arclength tracing of clamped crack clusters (lattice-trapping S-curves).

A clamped cluster (clusters.clamped_cluster) in a SinclairCrack with variable_alpha=False, energy=”total” is the problem: free atoms move, clamped atoms sit on the K-field. The tracer works in x = (u, k) with k = K/K_G and u the free-atom displacements relative to the field; the arclength metric is ds^2 = |du|^2 + alpha^2 dk^2. Correctors use a surrogate Jacobian (the Hessian of any matscipy many-body potential, e.g. Stillinger-Weber for Si, plus X-H springs, scaled by one calibrated factor) with good-Broyden updates from every force call, then Newton-Krylov. For large clusters the surrogate can stay sparse, with the Broyden updates as a low-rank correction (LowRankJacobian, TraceSettings(surrogate=”sparse”)).

Functions

bordered_solve(J, t, rhs_F, rhs_g)

Solve [J; t] d = [rhs_F; rhs_g] (the pseudo-arclength bordered system); J dense or a LowRankJacobian.

trace_s_curve(problem, surrogate, k0, *[, ...])

Trace the S-curve K(u) of a clamped crack cluster from load k0 = K/K_G.

Classes

BroydenCorrector([ftol, max_iter, ...])

Quasi-Newton on the bordered system F(y) = 0, t.(y - yp) = 0; B starts from the surrogate Jacobian and gets a good-Broyden rank-1 update from every force call.

ClampedProblem(crack, K_G[, atoms])

x = (u flat over free atoms, k = K/K_G) on a clamped SinclairCrack.

CorrectorResult(y, F, iters, calls, ok)

HessianSurrogate(problem, calc[, ks, kb, scale])

Approximate Jacobian dF/dx: the Hessian of calc (a matscipy many-body calculator with a hessian property) on the heavy atoms, times a calibrated scale, plus anisotropic X-H springs (stretch ks, bend kb, eV/A^2) for H caps (h_host).

KrylovCorrector([ftol, max_iter, eps_fd, ...])

Jacobian-free Newton-Krylov on the bordered system (GMRES; finite-difference J v, or an exact hvp(y, v) = J(y) v when given), right preconditioned by an approximate Jacobian (dense or LowRankJacobian); at most max_calls force calls (hvp calls are not counted).

LowRankJacobian(S[, U, V, max_rank])

Corrector Jacobian B = S + U V^T for large clusters (TraceSettings(surrogate="sparse")).

TraceSettings([ftol, alpha, ds0, ds_min, ...])

class matscipy.fracture_mechanics.continuation.ClampedProblem(crack, K_G, atoms=None)

Bases: object

x = (u flat over free atoms, k = K/K_G) on a clamped SinclairCrack. Free atoms: region 1 (groups != 0); clamped atoms ride the K-field. U is the field per unit k (all atoms).

atoms: the built cluster (clamped_cluster/cluster_like), whose geometry is the start; the crack’s own atoms at u = 0 put every H cap on its host (a cap’s reference is its host’s), so pass it whenever the cluster is passivated. k_build is the load the crack was set up at.

Attributes:
advance_break

Bond length (A) at which a crack-line bond counts as broken (settable).

line_bonds

Heavy-atom bonds crossing the cleavage plane at or ahead of the tip, sorted along the propagation direction: (i, j, reference length).

Methods

advance(x)

Crack advance in bonds: the sum over crack-line bonds of the fraction each is stretched from its reference length towards advance_break (clipped to [0, 1]).

evaluate(x)

(energy, forces on all atoms) at x; one force call unless x repeats the last one.

atoms_at

bond_between

dr_max

positions

residual

x_from

ADVANCE_BREAK_RATIO = 1.55
__init__(crack, K_G, atoms=None)
positions(x)
x_from(positions, k)
atoms_at(x)
evaluate(x)

(energy, forces on all atoms) at x; one force call unless x repeats the last one.

residual(x)
bond_between(x, i, j)
dr_max(x1, x0)
property advance_break

Bond length (A) at which a crack-line bond counts as broken (settable).

property line_bonds

Heavy-atom bonds crossing the cleavage plane at or ahead of the tip, sorted along the propagation direction: (i, j, reference length).

advance(x)

Crack advance in bonds: the sum over crack-line bonds of the fraction each is stretched from its reference length towards advance_break (clipped to [0, 1]).

class matscipy.fracture_mechanics.continuation.HessianSurrogate(problem, calc, ks=16.0, kb=1.5, scale=1.0)

Bases: object

Approximate Jacobian dF/dx: the Hessian of calc (a matscipy many-body calculator with a hessian property) on the heavy atoms, times a calibrated scale, plus anisotropic X-H springs (stretch ks, bend kb, eV/A^2) for H caps (h_host). jac is dense; jac_sparse keeps the calculator’s sparse Hessian sparse (for TraceSettings(surrogate=”sparse”)).

Methods

calibrate(x[, F0, n, eps, seed, clip])

Fit the scale from n finite-difference Hessian-vector products of the true forces along random unit vectors over the heavy-atom free dofs; clipped to clip.

hessian_sparse(x)

hessian as a scipy.sparse CSR matrix (3N x 3N), never densified.

jac_sparse(x)

jac as a scipy.sparse CSR matrix (nf x nf+1): [-H_II | dF/dk].

hessian

jac

__init__(problem, calc, ks=16.0, kb=1.5, scale=1.0)
hessian(x)
jac(x)
hessian_sparse(x)

hessian as a scipy.sparse CSR matrix (3N x 3N), never densified.

jac_sparse(x)

jac as a scipy.sparse CSR matrix (nf x nf+1): [-H_II | dF/dk].

calibrate(x, F0=None, n=2, eps=0.005, seed=0, clip=(0.3, 3.0))

Fit the scale from n finite-difference Hessian-vector products of the true forces along random unit vectors over the heavy-atom free dofs; clipped to clip.

class matscipy.fracture_mechanics.continuation.CorrectorResult(y: numpy.ndarray, F: numpy.ndarray, iters: int, calls: int, ok: bool)

Bases: object

y: ndarray
F: ndarray
iters: int
calls: int
ok: bool
__init__(y: ndarray, F: ndarray, iters: int, calls: int, ok: bool) → None
class matscipy.fracture_mechanics.continuation.LowRankJacobian(S, U=None, V=None, max_rank=120)

Bases: object

Corrector Jacobian B = S + U V^T for large clusters (TraceSettings(surrogate=”sparse”)).

S (nf x nf+1, scipy.sparse) is the surrogate Jacobian at the last refresh, U V^T (U: nf x m, V: nf+1 x m) the limited-memory good-Broyden correction learned from the true forces since, one column pair per update, compressed by truncated SVD to at most max_rank terms at each refresh. The bordered system [B; t] d = r is solved by block elimination on S’s free-free block S_u (one sparse LU per refresh, reused by the tangent, every corrector iteration and the Krylov preconditioner) and Sherman-Morrison-Woodbury for U V^T (S_u^-1 U cached), plus one step of iterative refinement, which guards the block elimination near folds, where S_u (a Hessian) is nearly singular. Exact algebra: the same B as the dense path, without the (3N)^2 storage and O(N^3) solves.

Attributes:
shape

Methods

bordered_solve(t, rhs_F, rhs_g[, refine])

Solve [B; t] d = [rhs_F; rhs_g], with refine steps of iterative refinement.

compress()

Truncated SVD of U V^T to at most max_rank terms (drops the smallest).

refresh(Sn[, mode, Q])

The B for a new surrogate Jacobian Sn (BroydenCorrector.refresh): "reset" Sn, "carry" Sn + U V^T, "projected" Sn + U V^T - (Sn - S) Q Q^T; compressed to max_rank.

update(dy, dF)

Good Broyden: B += (dF - B dy) dy^T / |dy|^2, as one new column pair.

copy

toarray

__init__(S, U=None, V=None, max_rank=120)
property shape
copy()
toarray()
update(dy, dF)

Good Broyden: B += (dF - B dy) dy^T / |dy|^2, as one new column pair.

refresh(Sn, mode='projected', Q=None)

The B for a new surrogate Jacobian Sn (BroydenCorrector.refresh): “reset” Sn, “carry” Sn + U V^T, “projected” Sn + U V^T - (Sn - S) Q Q^T; compressed to max_rank.

compress()

Truncated SVD of U V^T to at most max_rank terms (drops the smallest).

bordered_solve(t, rhs_F, rhs_g, refine=1)

Solve [B; t] d = [rhs_F; rhs_g], with refine steps of iterative refinement.

matscipy.fracture_mechanics.continuation.bordered_solve(J, t, rhs_F, rhs_g)

Solve [J; t] d = [rhs_F; rhs_g] (the pseudo-arclength bordered system); J dense or a LowRankJacobian.

class matscipy.fracture_mechanics.continuation.BroydenCorrector(ftol=0.002, max_iter=8, step_limit=0.1, max_rank=120)

Bases: object

Quasi-Newton on the bordered system F(y) = 0, t.(y - yp) = 0; B starts from the surrogate Jacobian and gets a good-Broyden rank-1 update from every force call. Q (orthonormal columns) spans the update directions since the last refresh: the subspace on which B holds secant information from the true forces rather than the surrogate’s. B is a dense array or a LowRankJacobian (max_rank terms, used when a refresh starts one from a sparse Jn).

Methods

refresh(Jn, Js[, mode])

Merge a new surrogate Jacobian Jn (previous one Js) into B and restart the span.

tangent(sec)

Unit null vector of B bordered by and oriented along the unit secant sec (sec if the bordered solve fails).

correct

update

__init__(ftol=0.002, max_iter=8, step_limit=0.1, max_rank=120)
update(dy, dF)
refresh(Jn, Js, mode='projected')

Merge a new surrogate Jacobian Jn (previous one Js) into B and restart the span.

“projected” adds Jn - Js only off the span Q: on Q, B already holds the true forces’ current secants, which contain that change, and adding it there too counts it twice per refresh (near a fold, where the critical curvature changes fast, this made the tangent retrace the stable branch). “carry” adds it everywhere (the behaviour before), “reset” sets B = Jn. A LowRankJacobian B takes the same rule on its low-rank part (Js is then its S). With no B yet, B = Jn (a LowRankJacobian if Jn is sparse); with no previous Js, a dense B has no change to merge and is kept.

tangent(sec)

Unit null vector of B bordered by and oriented along the unit secant sec (sec if the bordered solve fails).

correct(F_fn, y, Fy, yp, t, dr_fn)
class matscipy.fracture_mechanics.continuation.KrylovCorrector(ftol=0.002, max_iter=8, eps_fd=0.001, eta=0.2, gmres_max=60, step_limit=0.1, max_calls=40)

Bases: object

Jacobian-free Newton-Krylov on the bordered system (GMRES; finite-difference J v, or an exact hvp(y, v) = J(y) v when given), right preconditioned by an approximate Jacobian (dense or LowRankJacobian); at most max_calls force calls (hvp calls are not counted).

Methods

correct

__init__(ftol=0.002, max_iter=8, eps_fd=0.001, eta=0.2, gmres_max=60, step_limit=0.1, max_calls=40)
correct(F_fn, y, Fy, yp, t, dr_fn, prec_J=None, hvp=None)
class matscipy.fracture_mechanics.continuation.TraceSettings(ftol: float = 0.002, alpha: float = 2.0, ds0: float = 0.05, ds_min: float = 0.001, ds_max: float = 0.6, dr_cap: float = 0.05, n_target: int = 3, max_iter: int = 8, broyden_retries: int = 2, surrogate_every: int = 5, max_points: int = 400, k_window: tuple = (0.0, 3.0), stop_after_folds: int = 2, extra_after_last_fold: float = 0.25, reject_factor: float = 3.0, max_calls_per_point: int = 30, krylov_max_calls: int = 40, corrector_step_limit: float = 0.1, start_max_iter: int = 200, max_advance: float = None, tangent: str = 'jacobian', refresh: str = 'projected', surrogate: str = 'dense', max_rank: int = 120)

Bases: object

Attributes:
max_advance
ftol: float = 0.002
alpha: float = 2.0
ds0: float = 0.05
ds_min: float = 0.001
ds_max: float = 0.6
dr_cap: float = 0.05
n_target: int = 3
max_iter: int = 8
broyden_retries: int = 2
surrogate_every: int = 5
max_points: int = 400
k_window: tuple = (0.0, 3.0)
stop_after_folds: int = 2
extra_after_last_fold: float = 0.25
reject_factor: float = 3.0
max_calls_per_point: int = 30
krylov_max_calls: int = 40
corrector_step_limit: float = 0.1
start_max_iter: int = 200
max_advance: float = None
tangent: str = 'jacobian'
refresh: str = 'projected'
surrogate: str = 'dense'
max_rank: int = 120
__init__(ftol: float = 0.002, alpha: float = 2.0, ds0: float = 0.05, ds_min: float = 0.001, ds_max: float = 0.6, dr_cap: float = 0.05, n_target: int = 3, max_iter: int = 8, broyden_retries: int = 2, surrogate_every: int = 5, max_points: int = 400, k_window: tuple = (0.0, 3.0), stop_after_folds: int = 2, extra_after_last_fold: float = 0.25, reject_factor: float = 3.0, max_calls_per_point: int = 30, krylov_max_calls: int = 40, corrector_step_limit: float = 0.1, start_max_iter: int = 200, max_advance: float = None, tangent: str = 'jacobian', refresh: str = 'projected', surrogate: str = 'dense', max_rank: int = 120) → None
matscipy.fracture_mechanics.continuation.trace_s_curve(problem, surrogate, k0, *, direction=1, settings=None, callback=None)

Trace the S-curve K(u) of a clamped crack cluster from load k0 = K/K_G.

The start (the problem’s geometry, moved rigidly with the field from its build load to k0) is relaxed at fixed k; then a tangent predictor (tangent; capped to dr_cap and, with max_advance, to that crack advance) and bordered Broyden corrector (Newton-Krylov after broyden_retries halvings), with the surrogate Jacobian refreshed (refresh) every surrogate_every points. The corrector Jacobian is dense or sparse plus low rank (surrogate; the surrogate’s jac may return either). If the problem has hvp(x, v), the exact directional derivative of the free-atom forces dF/dx(x) v (x and v in (u, k)), Newton-Krylov uses it instead of finite differences of the forces. Folds are sign changes of dk/ds (not at the first point after the start); the branch label starts “stable” and alternates at each fold. Stops after stop_after_folds folds plus extra_after_last_fold in k, on leaving k_window moving outward, at max_points, or when a step needs more than max_calls_per_point force calls or ds falls below ds_min (“stalled”). callback(frame) is called for every accepted point.

Returns (frames, status): extxyz-ready Atoms with arrays forces and info K_over_KG, K, energy, branch, point_index, method, ds, calls; status one of “folds”, “window”, “complete”, “stalled”.