Python API¶

The GMXMMPBSA.API module provides programmatic access to parsed gmx_MMPBSA results. The current API is the same data layer used by gmx_MMPBSA_ana: it loads _GMXMMPBSA_info files or compact COMPACT_MMXSA_RESULTS.mmxsa files and returns pandas-based data structures for custom analysis.

Loading Results¶

Use load() for new code:

from GMXMMPBSA import API

api = API.load("COMPACT_MMXSA_RESULTS.mmxsa")

The same loader accepts an info file:

from GMXMMPBSA import API

api = API.load("_GMXMMPBSA_info")

If you need frame indexes expressed as simulation time, pass the same arguments accepted by MMPBSA_API.setting_time():

from GMXMMPBSA import API

api = API.load(
    "COMPACT_MMXSA_RESULTS.mmxsa",
    time={"timestep": 10, "timeunit": "ps"},
)

The lower-level class remains public:

from GMXMMPBSA.API import MMPBSA_API

api = MMPBSA_API()
api.setting_time(timestep=10, timeunit="ps")
api.load_file("COMPACT_MMXSA_RESULTS.mmxsa")

For a complete runnable example that loads a real compact result and writes a CSV file, see the Python API extraction example.

Metadata¶

The loaded object exposes calculation metadata:

info = api.get_info()
input_options = api.get_input()
files = api.get_files()

print(info["numframes"])
print(input_options["general"]["temperature"])
print(files.output_file)

get_info() returns a dictionary with values such as frame counts, output text, mutation information, and the complex PDB text. get_input() returns the parsed input namelists. get_files() returns the file namespace stored in the result.

Energy Data¶

get_energy() returns a dictionary with four main entries:

• map: available result keys after filtering.
• data: pandas DataFrames containing per-frame values plus Average, SD, and SEM rows.
• summary: pandas DataFrames containing only Average, SD, and SEM.
• correlation: compact energy summary used by correlation analysis.

Example:

energy = api.get_energy()

gb_delta = energy["data"]["normal"]["gb"]["delta"]
total = gb_delta["TOTAL"]

print(total.head())
print(energy["summary"]["normal"]["gb"]["delta"]["TOTAL"])

You can restrict the returned data:

energy = api.get_energy(
    etype=("normal",),
    model=("gb",),
    mol=("complex", "delta"),
    term=("VDWAALS", "EEL", "TOTAL"),
    startframe=1,
    endframe=100,
    interval=2,
)

Common etype values are normal, mutant, and mutant-normal. Common model values include gb, pb, rism std, rism gf, rism pcplus, and gbnsr6, depending on the calculation.

Key Reference¶

The keys available through the API depend on the calculation that produced the result file. For example, pb keys are only present when PB was run, mutant keys are only present for alanine scanning, and decomposition keys are only present when decomposition was enabled.

Use the returned map object to inspect what is actually available:

api = API.load("examples/API/COMPACT_MMXSA_RESULTS.mmxsa")

energy = api.get_energy()
entropy = api.get_entropy()

print(energy["map"])
print(entropy["map"])

# For a decomposition result:
# decomp = api.get_decomp_energy()
# print(decomp["map"])

Result Types¶

Molecular Components¶

Energy Models¶

Energy Terms¶

Entropy Models And Terms¶

Decomposition Keys¶

Return Object Keys¶

Entropy And Binding¶

get_entropy() combines available entropy methods:

entropy = api.get_entropy(model=("ie", "c2", "nmode", "qh"))
print(entropy["map"])

Specific helpers are also available:

ie = api.get_ie_entropy(ie_segment=25)
c2 = api.get_c2_entropy()
nmode = api.get_nmode_entropy()
qh = api.get_qh_entropy()

To compute binding tables that combine enthalpy and entropy summaries:

energy = api.get_energy()
entropy = api.get_entropy()

binding = api.get_binding(
    energy_summary=energy["summary"],
    entropy_summary=entropy["summary"],
)

print(binding["data"]["normal"]["gb"]["ie"])

Decomposition Data¶

get_decomp_energy() returns decomposition data when decomposition was enabled in the original calculation:

decomp = api.get_decomp_energy(
    model=("gb",),
    mol=("complex", "delta"),
    contribution=("TDC", "SDC"),
    res_threshold=0.5,
)

print(decomp["map"])
print(decomp["data"]["normal"]["gb"].head())

For pairwise decomposition, use res1 and res2 to restrict residue pairs. For per-residue decomposition, use res1 and term.

Analyzer Data¶

get_ana_data() prepares the same hierarchical data consumed by gmx_MMPBSA_ana. Public API use defaults to in-memory pandas objects:

ana_data = api.get_ana_data(
    energy_options={"etype": ("normal",)},
    entropy_options={"etype": ("normal",)},
    decomp_options={"res_threshold": 0.5},
    performance_options={"energy_memory": True, "decomp_memory": True},
    correlation=True,
)

Disk-backed analyzer data uses parquet files. If you request disk-backed data, install either pyarrow or fastparquet:

api = API.load("COMPACT_MMXSA_RESULTS.mmxsa", data_on_disk=True)
ana_data = api.get_ana_data(
    energy_options={},
    performance_options={"energy_memory": False, "decomp_memory": True},
)

Compatibility Loader¶

load_gmxmmpbsa_info() is kept for older imports:

from GMXMMPBSA import API

api = API.load_gmxmmpbsa_info("_GMXMMPBSA_info")
energy = api.get_energy()

This compatibility function intentionally returns the modern MMPBSA_API object. Scripts written for the old dict-like API should be migrated to get_energy()["data"], get_entropy()["data"], and get_decomp_energy()["data"].

Validation Status¶

This API modernization is intentionally staged on a separate branch. The current minimum validation target is:

python3 -m py_compile GMXMMPBSA/API.py

Import and fixture-loading smoke tests should be run in the supported Python 3.11 environment with the project dependencies installed. Full API regression coverage is deferred until the public interface is reviewed.