ABAQUS CONTACT & HYBRID CONSTRAINT MONITOR — VERSION 1.0
=========================================================

PURPOSE
-------
This program is a sister diagnostic tool to the Abaqus force-residual and
 displacement-correction convergence monitor. It reads an Abaqus/Standard .msg
file and follows two additional parts of nonlinear convergence:

1. Contact-state consistency and local contact errors.
2. Hybrid-element volumetric compatibility.

The tool is intended for Windows and requires no third-party Python packages.
It uses Abaqus Python first, then standard Windows Python if available.

HOW TO START
------------
1. Extract all files to one folder.
2. Double-click:

   Run_Abaqus_Contact_Hybrid_Monitor.bat

3. Select the running or completed Abaqus .msg file.
4. Enable "Auto-refresh every 5 s" to follow a running job.

WHAT IS EXTRACTED
-----------------
For every SDI and regular equilibrium iteration, the program extracts:

- Step, increment, attempt, iteration, and time increment.
- Number of severe discontinuities.
- Open-to-closed and closed-to-open contact changes.
- Slipping-to-sticking and sticking-to-slipping changes.
- Maximum penetration error, node, and contact pair.
- Maximum estimated contact-force error, node, and contact pair.
- Number of closed and open contact constraints.
- Abaqus contact convergence statement.
- Hybrid volumetric compatibility error.
- Number of hybrid elements exceeding tolerance.
- Element containing the maximum hybrid error.
- Active contact and hybrid tolerances printed in the .msg file.

NORMALIZED CONTACT MEASURES
---------------------------
When CONVERT SDI=YES, Abaqus uses a local contact/slip compatibility measure.
The monitor calculates:

   penetration ratio = |maximum penetration error|
                       --------------------------------
                       |largest displacement increment|

and compares it with the active contact/slip compatibility tolerance printed
in the .msg file.

The monitor also calculates:

   contact-force ratio = |maximum estimated contact-force error|
                         ----------------------------------------
                         |active force reference norm|

and compares it with the active contact-force error tolerance.

The exact Abaqus text remains authoritative. The tool displays whether Abaqus
reported penetration too large, force error outside tolerance, SDI errors within
tolerance, or contact constraints converged.

HYBRID COMPATIBILITY MEASURE
----------------------------
The monitor calculates:

   hybrid ratio = |maximum volumetric compatibility error|
                  ------------------------------------------
                  |active volumetric compatibility tolerance|

A value below 1.0, together with zero elements exceeding tolerance, indicates
that the hybrid volumetric constraint is within the active tolerance.

THREE PLOT TABS
---------------
1. Contact errors
   - Penetration/displacement ratio.
   - Contact-force error/force-norm ratio.
   - Active tolerance lines.

2. Contact status changes
   - Total severe discontinuities.
   - Open/closed transitions.
   - Stick/slip transitions.
   A trend toward zero indicates that the active contact set is settling.
   A small nonzero plateau can indicate contact chattering.

3. Hybrid compatibility
   - Maximum volumetric compatibility error normalized by tolerance.
   - Numbers above plotted points show how many hybrid elements exceed tolerance.

IMPORTANT INTERPRETATION
------------------------
This monitor does not replace the force-residual/displacement-correction monitor.
An accepted nonlinear increment requires all applicable checks to be acceptable:

- contact state and local contact errors;
- force residual;
- displacement correction;
- moment/rotation checks when active;
- hybrid or other constraint compatibility checks.

A contact configuration can be settling while the field equations remain
unconverged. Likewise, force equilibrium can improve while contact continues to
chatter or the hybrid compatibility constraint remains outside tolerance.

CSV EXPORT
----------
Click "Export CSV" to save all parsed records.

Command-line export is also available:

   abaqus python abaqus_contact_hybrid_monitor.py model.msg --csv output.csv

LIVE FILE USE
-------------
The parser reads only newly appended content during refresh, so it can monitor a
large running .msg file without rereading the entire file every five seconds.

LIMITATIONS
-----------
- The parser recognizes common Abaqus/Standard 2024-2026 message-file wording.
- It reads summary diagnostics printed in the .msg file; it does not identify
  every individual contact point. Detailed point-by-point diagnosis may require
  Abaqus/CAE contact diagnostics, .dat contact print output, or ODB inspection.
- For unusual procedures or customized output wording, inspect the CSV and the
  original .msg file before drawing conclusions.
