OpenSeesMatlabAnalysis

analysis.OpenSeesMatlabAnalysis

Bases: handle

Analysis management interface for OpenSeesMatlab.

OpenSeesMatlabAnalysis groups analysis-related helpers used by the main OpenSeesMatlab object.

Properties:

• smartAnalyze (analysis.SmartAnalyze) –

  Robust analysis helper for convergence recovery and progress tracking

• MomentCurvature (analysis.MomentCurvature) –

  Helper for moment-curvature analysis of opensees sections. See analysis.MomentCurvature for full documentation.

smartAnalyze SetAccess=private

smartAnalyze: analysis.SmartAnalyze

Robust analysis helper for convergence recovery and progress tracking

MomentCurvature SetAccess=private

MomentCurvature: analysis.MomentCurvature

Helper for moment-curvature analysis of opensees sections. See analysis.MomentCurvature for full documentation.

analysis.SmartAnalyze

Bases: handle

SmartAnalyze manages robust OpenSees analysis retries for OpenSeesMatlab.

SmartAnalyze stores analysis configuration, progress information, and retry strategies for transient and displacement-control static analyses. It is intended to be accessed through OpenSeesMatlabAnalysis:

  opsmat = OpenSeesMatlab();
  smartAnalyze = opsmat.anlys.smartAnalyze;

OpenSeesMatlabAnalysis automatically calls setOPS with the OpenSees command interface. If SmartAnalyze is used directly, call setOPS or setOps before configure, transientAnalyze, or staticAnalyze.

Retry order

Each failed analysis step is retried in this order:

1. Add convergence-test iteration limits, if tryAddTestTimes is true.
2. Try alternate algorithm types, if tryAlterAlgoTypes is true.
3. Try alternate convergence-test types, if tryAlterTestTypes is true.
4. Loosen the test tolerance, if tryLooseTestTol is true.
5. Split the current step using relaxation until minStep is reached, if tryRelaxStep is true.

Step relaxation is intentionally tried last because successful substeps can partially advance the OpenSees model state. Keeping it last avoids applying other whole-step retry strategies after the model has already moved through part of the requested step.

Performance

SmartAnalyze is a handle class. All property access and method calls operate directly on the object without copying state, giving O(1) overhead per step regardless of analysis length. normHistory uses a struct-of-columns layout so that appending is O(1) amortised. diagnostics.records is a fixed-capacity ring buffer so memory is bounded at maxRecords entries.

Example

  % Transient analysis with full retry strategies
  opsmat = OpenSeesMatlab();
  ops = opsmat.ops;
  sa = opsmat.anlys.smartAnalyze;

  ops.wipeAnalysis();
  ops.constraints('Plain');
  ops.numberer('RCM');
  ops.system('UmfPack');

  sa.configure(...
      analysis="Transient", testType="EnergyIncr", testTol=1e-10, ...
      testIterTimes=100, tryAddTestTimes=true, normTol=1e3, ...
      testIterTimesMore=[50 100], tryLooseTestTol=true, ...
      looseTestTolTo=[1e-8, 1e-6], tryAlterTestTypes=true, ...
      testTypesMore=["NormDispIncr","NormUnbalance"], ...
      tryAlterAlgoTypes=true, algoTypes=[40 10 20 30], ...
      tryRelaxStep=true, relaxation=0.5, minStep=1e-6, ...
      recordNormHistory=true, debugMode=true, printPer=100);

  sa.setTotalSteps(1000);
  for i = 1:1000
      ok = sa.transientAnalyze(0.01);
      if ok < 0, error("Transient analysis failed at step %d.", i); end
  end
  history = sa.getNormHistory();
  sa.reset();

  %--- Static pushover (minimal settings) ---
  sa.configure(analysis="Static", testType="EnergyIncr", testTol=1e-8, ...
      tryAlterAlgoTypes=true, algoTypes=[40 10 20], tryRelaxStep=true, ...
      minStep=1e-6, recordNormHistory=true, debugMode=false);

  segs = sa.staticStepSplit([0; 0.5; 1.0], 0.1);
  for i = 1:numel(segs)
      ok = sa.staticAnalyze(1, 1, segs(i));
      if ok < 0, error("Static analysis failed at segment %d.", i); end
  end
  sa.reset();

initialize

(npts: double = 0)

Reset cfg to defaults; keep only ops. configure() must be called after.

Preserved : ops Cleared : cfg, sensitivityAlgorithm, history, progress, diagnostics

Input arguments:

• npts (double) –

  Expected total steps (default 0 = no progress tracking).

configure

(analysis: string = string(missing), testType: string = string(missing), testTol: double = NaN, testIterTimes: double = NaN, testPrintFlag: double = NaN, tryAddTestTimes=[], normTol: double = NaN, testIterTimesMore: double = NaN, tryLooseTestTol=[], looseTestTolTo: double = NaN, tryAlterTestTypes=[], testTypesMore=[], recordNormHistory=[], recordDiagnostics=[], tryAlterAlgoTypes=[], algoTypes: double = NaN, UserAlgoArgs: cell = {}, tryRelaxStep=[], initialStep: double = NaN, relaxation: double = NaN, minStep: double = NaN, debugMode=[], printPer: double = NaN)

Configure analysis settings and apply the initial test and algorithm.

Syntax

sa.configure(Name=Value)

Notes

setOPS must be called before configure. configure immediately
applies the convergence test and first algorithm to OpenSees.

Input arguments:

• analysis (string) –

  Analysis type: "Transient" (default) or "Static".

• testType (string) –

  OpenSees convergence test type. Default is "EnergyIncr". Supported values:

  • "EnergyIncr" : half inner product of disp incr and unbalance
  • "NormUnbalance" : norm of unbalanced load vector
  • "NormDispIncr" : norm of displacement increment vector
  • "RelativeNormUnbalance" : NormUnbalance relative to first iteration
  • "RelativeNormDispIncr" : NormDispIncr relative to first iteration
  • "RelativeTotalNormDispIncr" : NormDispIncr relative to total displacement norm
  • "RelativeEnergyIncr" : EnergyIncr relative to first iteration
  • "FixedNumIter" : always runs exactly testIterTimes iterations
  • "NormDispAndUnbalance" : both NormDispIncr and NormUnbalance must pass
  • "NormDispOrUnbalance" : either NormDispIncr or NormUnbalance must pass
• testTol (double) –

  Convergence tolerance. Default 1e-10.

• testIterTimes (double) –

  Maximum convergence-test iterations. Default 10.

• testPrintFlag (double) –

  OpenSees test print flag. Default 0.

• tryAddTestTimes (logical) –

  Retry with more iterations when norm < normTol. Default false.

• normTol (double) –

  Norm threshold for tryAddTestTimes. Default 1e3.

• testIterTimesMore (double array) –

  Extra iteration limits to try. Default 50.

• tryLooseTestTol (logical) –

  Retry with looser tolerance. Default false.

• looseTestTolTo (double or array) –

  Looser tolerance(s). Default 100*testTol.

• tryAlterTestTypes (logical) –

  Retry with alternate test types. Default false.

• testTypesMore (string array or cell) –

  Alternate test types. Default {'NormDispIncr','NormUnbalance','RelativeEnergyIncr'}. Supported values are the same as for testType (see above).

• tryAlterAlgoTypes (logical) –

  Retry with fallback algorithms. Default false.

• algoTypes (double array) –

  Algorithm codes. First entry applied at configure time. Default [40 10 20 30 50 60 70 90]. Supported codes:

  • 0..5 : Linear variants
  • 10..13: Newton variants
  • 20..25: NewtonLineSearch variants
  • 30..32: ModifiedNewton variants
  • 40..45: KrylovNewton variants
  • 50..53: SecantNewton variants
  • 60..62: BFGS variants
  • 70..72: Broyden variants
  • 80..81: PeriodicNewton variants
  • 90..91: ExpressNewton variants
  • 100 : user-defined (requires UserAlgoArgs)
• UserAlgoArgs (cell array) –

  Arguments for algorithm type 100.

• tryRelaxStep (logical) –

  Split failed steps into sub-steps. Default true.

• relaxation (double) –

  Sub-step shrink factor. Default 0.5.

• minStep (double) –

  Minimum sub-step size. Default 1e-6.

• initialStep (double) –

  Stored initial step (overwritten by transientAnalyze/staticAnalyze).

• recordNormHistory (logical) –

  Record per-step norm summaries. Default true.

• recordDiagnostics (logical) –

  Record detailed failure diagnostics. Default false.

• debugMode (logical) –

  Print retry and progress messages. Default false.

• printPer (double) –

  Print progress every N successful steps. Default 20.

Example

sa.configure(analysis="Transient", testTol=1e-10, ...
    tryAlterAlgoTypes=true, algoTypes=[40 10 20], ...
    tryRelaxStep=true, minStep=1e-6, debugMode=true);

reset

()

Clear history and progress; preserve ops and cfg.

After reset(), analysis can resume immediately without calling configure() again.

Preserved : ops, cfg, sensitivityAlgorithm Cleared : normHistory, diagnostics, progress, lastNorms

setTotalSteps

(npts: double)

Reset and set total expected steps for progress tracking.

Calls reset() then sets npts. configure() is not required again.

Input arguments:

• npts (double) –

  Total expected steps; rounded to nearest integer.

staticStepSplit

(targets: double, maxStep: double = NaN)

Split displacement-control targets into bounded static steps.

Input arguments:

• targets ((:,1) double) –

  Target displacements. Scalar treated as [0; target].

• maxStep (double) –

  Maximum segment size. Default: |targets(2)-targets(1)|.

Output arguments:

• segs ( column vector of displacement increments ) –

staticAnalyze

(nodeTag: double, dof: double, seg: double)

Run one displacement-control static analysis step with retries.

Input arguments:

• nodeTag (positive integer) –

  Node tag for DisplacementControl integrator.

• dof (positive integer) –

  Degree of freedom for DisplacementControl integrator.

• seg (double) –

  Displacement increment.

Output arguments:

• ok ( 0 on success; negative on failure. ) –

transientStepSplit

(npts: double)

Split transient analysis into step indices for progress tracking.

Input arguments:

• npts (double) –

  Number of transient steps.

Output arguments:

• segs ( 1:npts row vector ) –

transientAnalyze

(dt: double)

Run one transient analysis step with automatic retry strategies.

Input arguments:

• dt (double) –

  Time-step size for ops.analyze(1, dt).

Output arguments:

• ok ( 0 on success; negative on failure. ) –

setSensitivityAlgorithm

(algorithm: string)

Set the OpenSees sensitivity algorithm for static analysis.

Input arguments:

• algorithm (string) –

  "-computeAtEachStep" or "-computeByCommand".

getNormHistory

()

Get convergence norm history as a struct array.

Output arguments:

• history ( struct array with fields stepIndex, strategy, ok, ) –

  firstNorm, lastNorm, minNorm, maxNorm, numIter, improvementRatio, isDiverging, isStagnating.

Example

history = sa.getNormHistory();
figure; semilogy([history.lastNorm], '.'); grid on;

getDiagnostics

()

Get failure diagnostics collected during analysis.

Output arguments:

• diagnostics ( struct with fields records, lastFailure, maxRecords. ) –

Example

d = sa.getDiagnostics();
sa.printLastFailure();

printLastFailure

()

Print a concise diagnostic report for the most recent failure.

Example

sa.printLastFailure();

analysis.MomentCurvature

Bases: handle

MomentCurvature Moment-curvature analysis and N-My-Mz interaction surface for fiber sections.

Typical usage

opsmat = OpenSeesMatlab();
mc     = opsmat.anlys.MomentCurvature;
mc.new(secTag, axialForce);
mc.analyze('axis','y','maxPhi',0.05,'incrPhi',1e-4);
mc.plotMPhi();
[phiU, MU] = mc.getLimitState('matTag',1,'threshold',-0.003);
mc.bilinearize(phiY, MY, phiU, 'plot', true);

mc.buildNMM('NList', linspace(-2000e3,0,10)', ...
            'phiMax',0.05,'nTheta',36,'useParallel',true);
mc.plotNMM();

new

(secTag: double, axialForce: double = 0)

Re-initialise this instance with a new section and axial load.

Input arguments:

• secTag (double) –

  Tag of the previously defined fiber section.

• axialForce (double) –

  Constant axial load. Compression negative. Default 0.

Output arguments:

• obj ( MomentCurvature ) –

  The same handle object, re-initialised in place.

Example

% Reuse the same ops handle for a new section / axial load.
mc = mc.new(2, -500e3);

analyze

(axis: char = 'y', maxPhi: double = 0.05, incrPhi: double = 1e-4, limitPeakRatio: double = 0.8, cycleAnalyze: logical = false, smartAnalyze: logical = true)

Run the moment-curvature analysis.

Input arguments:

• axis (('y', 'z'), default: 'y','z' ) –

  Bending axis. Default 'y'.

• maxPhi (double) –

  Maximum target curvature. Default 0.05.

• incrPhi (double) –

  Base curvature increment. Default 1e-4.

• limitPeakRatio (double) –

  Post-peak stop ratio. Default 0.8.

• cycleAnalyze (logical) –

  Follow the path from setCyclePath. Default false.

• smartAnalyze (logical) –

  Adaptive step-halving + algorithm rotation. Default true.

Notes

Results written to obj.phi, obj.M, obj.FiberData.

setCyclePath

(maxPhi: double, nCycle: double = 20, nHold: double = 1)

Build a symmetric incrementally-growing cyclic path.

Input arguments:

• maxPhi (double) –

  Peak curvature (sign ignored; both directions included).

• nCycle (int) –

  Number of amplitude levels. Default 20.

• nHold (int) –

  Repetitions at each amplitude level. Default 1.

Output arguments:

• path ( double array, shape (1 + (nCycle-1)*2*nHold + 1,) ) –

  Curvature target sequence, stored in obj.cyclePath. Starts and ends at 0.

getMPhi

()

Return curvature and moment arrays.

Output arguments:

• phi ( double array, shape (nStep,) ) –
• M ( double array, shape (nStep,) ) –

getCurvature

()

Return the curvature array.

Output arguments:

• phi ( double array, shape (nStep,) ) –

getMoment

()

Return the moment array.

Output arguments:

• M ( double array, shape (nStep,) ) –

getLimitState

(matTag=1, threshold=0.0, peakDrop=[])

Locate the curvature and moment at a limit state.

Two modes (mutually exclusive):

Strain-threshold mode (default) First step at which any monitored fiber reaches the given strain threshold. Positive threshold -> tensile strain limit. Negative threshold -> compressive strain limit.

Peak-drop mode (peakDrop supplied) First post-peak step at which |M| <= (1-peakDrop)*|M_peak|. Both positive and negative moment directions handled via abs(M).

Input arguments:

• matTag (scalar or vector) –

  Material tag(s) to monitor. Default 1.

• threshold (scalar or vector) –

  Strain threshold(s). Scalar is broadcast to all matTags. Default 0.0.

• peakDrop (double in (0, 1)) –

  Fractional strength drop, e.g. 0.20 = 20 % drop. When supplied, matTag / threshold are ignored.

Output arguments:

• phiU ( double - curvature at the limit state. ) –
• MU ( double - moment at the limit state. ) –
• idxU ( int - step index (1-based). ) –

bilinearize

(phiY: double, MY: double, phiU: double, plot: logical = false, ax=[])

Equal-area bilinear approximation of M-phi.

Elastic branch slope k = MY/phiY is preserved. phiEq and MEq are found by equating the area under the bilinear curve to the area under the actual M-phi curve up to phiU.

Both positive and negative loading directions are supported: the calculation is performed in absolute-value space and mapped back to the original sign convention on return.

Input arguments:

• phiY (double) –

  initial yield curvature (pos or neg).

• MY –

  initial yield moment (pos or neg).

• phiU (double) –

  limit curvature (pos or neg).

• plot (logical) –

  plot bilinear overlay. Default false.

• ax –

  target axes; new figure if empty.

Output arguments:

• phiEq ( double ) –

  equivalent yield curvature.

• MEq ( double ) –

  equivalent yield moment.

• idxU ( int ) –

  index in obj.phi nearest to phiU on branch.

plotMPhi

(ax=[])

Plot the moment-curvature relationship.

Input arguments:

• ax (Axes) –

  target axes; new figure if empty.

plotFiberResponses

(matTag=[], lineWidth: double = 1.0, maxFibers: double = Inf, shareX: logical = true, shareY: logical = false)

Stress-strain histories by selected material tag(s).

One subplot per selected material tag; all fibers of that material are plotted in a single vectorised plot() call.

Input arguments:

• matTag (scalar or array) –

  Material tag(s) to visualize. If empty, all material tags are used.

• lineWidth (double) –

  Curve line width. Default 0.7.

• maxFibers (double) –

  Maximum number of fibers per material. Uniform subsampling is used when the number of fibers exceeds this value. Default Inf.

• shareX –

  Link subplot axes. Default true / false.

Output arguments:

• axs ( Axes array, shape (nSelectedMaterials,) ) –

buildNMM

(NList: double = linspace(-1e6,0,8)', axis1: char = 'y', axis2: char = 'z', phiMax: double = 0.05, incrPhi: double = 1e-4, nTheta: double = 36, limitPeakRatio: double = 0.8, smartAnalyze: logical = true, useParallel: logical = false, capacityMode: char = 'peak', peakDrop: double = 0.20, matTag=1, threshold=0.0, targetPhi: double = NaN, MyCapManual: double = [], MzCapManual: double = [])

Compute the approximate N-My-Mz interaction surface.

Algorithm

For each N_i two uniaxial analyses (axis-y, axis-z) yield \(M_{y,Cap}(N_i)\) and \(M_{z,Cap}(N_i)\). The n Theta-point contour is then computed analytically from the ellipse formula:

$$ \left(\frac{M_y}{M_{y,Cap}}\right)^2 + \left(\frac{M_z}{M_{z,Cap}}\right)^2 = 1 $$

Capacity modes

• 'peak' max(|M|) over the full run.
• 'peakDrop' first post-peak point where |M|<=(1-drop)*|M_peak|.
• 'strain' first step where a fiber strain reaches threshold.
• 'curvature' |M| at the curvature nearest to targetPhi.
• 'manual' user-supplied MyCapManual / MzCapManual.

Input arguments:

• NList –

  axial loads, compression<0.

• axis1 –

  bending axes. Default 'y','z'.

• phiMax –

  max curvature. Default 0.05.

• incrPhi –

  base increment. Default 1e-4.

• nTheta –

  direction divisions. Default 36.

• limitPeakRatio (double) –

  stop ratio per run. Default 0.8.

• smartAnalyze –

  adaptive step. Default true.

• useParallel –

  parfor (PCT). Default false.

• capacityMode –

  see above. Default 'peak'.

• peakDrop –

  drop ratio. Default 0.20.

• matTag –

  for 'strain' mode.

• threshold –

  for 'strain' mode.

• targetPhi –

  for 'curvature' mode.

• MyCapManual –

  for 'manual' mode.

• MzCapManual –

  for 'manual' mode.

plotNMM

(normalize: logical = false, alpha: double = 0.5, colormap: char = 'turbo', showSurface: logical = true, showPlanView: logical = true, showEnvelope: logical = true)

Render the N-My-Mz interaction surface (up to 3 figures).

• Figure 1 (showSurface) - 3-D surface + per-N contour rings + generatrix lines.
• Figure 2 (showPlanView) - My-Mz plan view, one contour per N.
• Figure 3 (showEnvelope) - Uniaxial N-MyCap and N-MzCap lines.

Input arguments:

• normalize –

  normalise axes. Default false.

• alpha –

  surface transparency. Default 0.5.

• colormap –

  colormap name. Default 'turbo'.

• showSurface –

  toggle Fig 1. Default true.

• showPlanView (logical) –

  toggle Fig 2. Default true.

• showEnvelope (logical) –

  toggle Fig 3. Default true.

Output arguments:

• axs ( struct - fields: surface, plan, envelope. ) –

  Suppressed figures have [].