Gaussian interface for local MLP/MACE models

中文说明

This repository provides a local Gaussian external interface for machine-learning interatomic potentials. The current implementation is built around two scripts:

• server.py: starts and manages a persistent local model server.
• mlpint_local.py: the script called by Gaussian through the external= keyword.

The workflow is:

1. Start server.py once.
2. Gaussian calls mlpint_local.py during the job.
3. mlpint_local.py parses Gaussian's external input, sends a request to the local server, and writes energy / gradient / optional Hessian back in Gaussian's external output format.

What is in the repository

File	Purpose
server.py	Persistent local TCP service for loading the model and evaluating structures
mlpint_local.py	Gaussian external bridge script
examples/complex_1.gjf	Example Gaussian input using external='python ./mlpint_local.py'
examples/complex_1.out	Example Gaussian output showing optimization and frequency analysis

How it works

1. Persistent local server

server.py loads the ML calculator once and listens on 127.0.0.1 on an automatically assigned port. It stores the port in mlpint_server_port.json, so later Gaussian calls can reuse the same process instead of reloading the model every step.

Main server commands:

• start: start the persistent server
• status: check whether the server is running
• exit: stop the server

2. Gaussian external bridge

mlpint_local.py is not a standalone optimization program. It is a bridge script used by Gaussian.

For each external call, it:

1. reads Gaussian's external input file;
2. parses atom count, derivative level, charge, multiplicity, element labels / atomic numbers, and coordinates;
3. converts coordinates from Bohr to Angstrom;
4. sends the structure to the local server through a TCP socket;
5. receives energy, gradient, and optional Hessian;
6. writes the result back in Gaussian external output format.

3. Property evaluation

Inside server.py, the request is turned into an ase.Atoms object and evaluated with MACECalculator.

• Energy is returned in Hartree for Gaussian.
• Gradient is derived from forces and converted to Gaussian units.
• Hessian can be computed in two modes:
  • numeric: via ase.vibrations.Vibrations
  • analytic: via calculator.get_hessian(atoms) if the calculator supports it

Confirmed dependencies

This repository does not currently provide a dedicated dependency file. From the current source imports, the runtime depends at least on:

• numpy
• torch
• ase
• mace
• Gaussian with support for the external interface

If your environment uses different package names or installation methods, install the equivalents that provide these Python imports.

Starting the local server

Example commands from the repository:

CatESP / MACE-style model

python ./server.py start --model CatESP --device cuda --threads 1 --hessian numeric --background --debug

Fairchem-style alias example

python ./server.py start --model s --device cuda --threads 1 --hessian numeric --background --debug

Check status:

python ./server.py status

Stop the server:

python ./server.py exit

Notes on model selection

--model accepts either:

• a built-in alias such as CatESP, s, small, m, medium, mace, mace-omol, mace-polar-m, mace-polar-l; or
• an explicit model path.

If the alias-based path resolution does not match your local model layout, pass the full path explicitly with --model.

Gaussian input example

The repository includes examples/complex_1.gjf, which runs an optimization and then a frequency job through Link1.

Example route sections:

# external='python ./mlpint_local.py' opt(calcfc,nomicro,maxcycle=1000)

and later:

# freq external='python ./mlpint_local.py' geom=allcheck

A minimal pattern is:

%nprocshared=1
%mem=8GB
%chk=job.chk
# external='python ./mlpint_local.py' opt(calcfc,nomicro,maxcycle=1000)

Title

0 1
... coordinates ...

Optional interface-script flags

mlpint_local.py also supports these options before Gaussian's trailing arguments:

• --port-file <path>: override the server port file
• --timeout <seconds>: response timeout (0 means no timeout)
• --debug: enable detailed logging
• --debug-log <path>: write debug logs to a custom file

By default, the script looks for mlpint_server_port.json next to itself.

Understanding the example output

examples/complex_1.out shows that the interface can drive both geometry optimization and a frequency job.

Useful markers in the output are:

• Optimization completed.
• -- Stationary point found.
• Normal termination of Gaussian 16

The same example also contains lines such as:

• Frequencies -- -41.4314 -21.4308 -11.8975

So the sample demonstrates that the workflow runs successfully, but the final structure in that example is not a strict local minimum because the frequency analysis contains imaginary frequencies.

Debugging

Server-side debugging

Start the server with --debug to write a server debug log. The server also tracks the active port file through:

• mlpint_server_port.json
• mlpint_server_active.json

Gaussian-side debugging

Enable --debug in mlpint_local.py if you need per-job diagnostics. The script writes a debug log path to Gaussian's message file.

Common failure points

• Server not started: mlpint_local.py will fail if the port file does not exist.
• Model file not found: server.py checks the resolved model path before starting.
• Unsupported analytic Hessian: use --hessian numeric if your calculator does not implement get_hessian().
• Path mismatch in Gaussian: make sure the external='python ./mlpint_local.py' path is valid from the Gaussian working directory.

Notes

• The current implementation is a local TCP service plus a Gaussian external bridge script.