Abaqus .msg Convergence Monitor — Windows
Version 1.2
==========================================

Purpose
-------
This tool reads an Abaqus/Standard message (.msg) file and extracts the
nonlinear convergence progression used during model debugging.

Version 1.2 corrections
-----------------------
Version 1.1 could collapse an entire attempt into one row when Abaqus printed:

    AVERAGE FORCE ... USER DEF. NORM ...

instead of:

    AVERAGE FORCE ... TIME AVG. FORCE ...

This occurred when a user-defined average force norm was supplied through
*CONTROLS. Version 1.2 now:

- parses USER DEF. NORM as the active force reference;
- computes residual ratio using that printed reference;
- parses every severe-discontinuity iteration (SDI) as well as every regular
  equilibrium iteration;
- shows both the overall chronological iteration number and the Abaqus
  iteration kind/number;
- parses the active force-residual and displacement-correction tolerances from
  the Abaqus step controls;
- plots the active tolerances rather than always plotting the default 0.005 and
  0.01 reference lines;
- recognizes "THE FORCE EQUILIBRIUM EQUATIONS HAVE CONVERGED."

Extracted information
---------------------
- Step / increment / attempt
- Overall chronological solver iteration
- Iteration kind: SDI or EQ
- Abaqus iteration number within that kind
- Time increment
- Average force
- Active force reference: TIME AVG or USER NORM
- Largest residual force, node, and DOF
- Residual ratio
- Active force residual tolerance
- Largest displacement increment
- Largest displacement correction, node, and DOF
- Correction ratio
- Active displacement correction tolerance
- Force-equilibrium status and selected convergence notes
- Increment cutback attempts

The normalized measures are:

    |largest residual force| / |printed force reference|

where the printed reference is either TIME AVG. FORCE or USER DEF. NORM, and:

    |largest displacement correction| / |largest displacement increment|

Windows quick start
-------------------
1. Keep these files in the same folder:

   abaqus_msg_convergence_monitor.py
   Run_Abaqus_MSG_Monitor.bat

2. Double-click:

   Run_Abaqus_MSG_Monitor.bat

3. Click "Open .msg" and select the Abaqus/Standard message file.

4. For a running analysis, enable:

   Auto-refresh every 5 s

Python requirement
------------------
The batch file first tries the Python interpreter bundled with Abaqus:

    abaqus python abaqus_msg_convergence_monitor.py

It then falls back to a standard Windows Python 3 installation if available.
No matplotlib, pandas, NumPy, or other third-party package is required.

Command-line CSV mode
---------------------
With Abaqus Python:

    abaqus python abaqus_msg_convergence_monitor.py job.msg --csv job_convergence.csv

Diagnostic trend logic
----------------------
The diagnostic distinguishes a truly shrinking Newton displacement correction
from a correction ratio that falls only because the accumulated displacement
increment grows. It also checks for correction growth, oscillation, and
near-self-similar trajectories repeated after cutbacks.

The trend remains a diagnostic heuristic. The active Abaqus tolerances are
shown separately and are not replaced by the heuristic.
