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
|
Solve [J; t] d = [rhs_F; rhs_g] (the pseudo-arclength bordered system); J dense or a LowRankJacobian. |
|
Trace the S-curve K(u) of a clamped crack cluster from load k0 = K/K_G. |
Classes
|
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. |
|
x = (u flat over free atoms, k = K/K_G) on a clamped SinclairCrack. |
|
|
|
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). |
|
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). |
|
Corrector Jacobian B = S + U V^T for large clusters (TraceSettings(surrogate="sparse")). |
|
- class matscipy.fracture_mechanics.continuation.ClampedProblem(crack, K_G, atoms=None)
Bases:
objectx = (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_breakBond length (A) at which a crack-line bond counts as broken (settable).
line_bondsHeavy-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:
objectApproximate 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 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:
objectCorrector 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()
- 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:
objectQuasi-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:
objectJacobian-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”.