MEPGL

MEPGL computes minimum-energy paths in two-dimensional Ginzburg–Landau models using the gauged string method. It supports arbitrary sample geometries, anisotropic condensates, single- and two-component models, and user-defined initial paths.

The free energy is

$$\begin{aligned} F[\mathbf{A}, \psi_1, \psi_2] ={}& \sum_{\alpha=1,2} \left[ \sum_{k=x,y} \frac{|D_k \psi_\alpha|^2}{2m_{\alpha,kk}} + \frac{b_\alpha}{2} \left(\frac{a_\alpha}{b_\alpha} + |\psi_\alpha|^2\right)^2 \right] \ &+ \frac{1}{2}(\nabla \times \mathbf{A} - \mathbf{H})^2 + V_{\mathrm{int}}(\psi_1, \psi_2). \end{aligned}$$

with linear Josephson, density, and biquadratic Josephson interactions,

$$\begin{aligned} V_{\mathrm{int}}(\psi_1, \psi_2) ={}& \frac{\eta}{2}(\psi_1\psi_2^* + \mathrm{c.c.}) + \frac{\gamma}{2}|\psi_1|^2|\psi_2|^2 \ &+ \frac{\delta}{4}\left([\psi_1\psi_2^*]^2 + \mathrm{c.c.}\right). \end{aligned}$$

Installation

The complete package is distributed through the andmai/science prefix.dev channel. Create an isolated Pixi project and add MEPGL:

mkdir mepgl-project
cd mepgl-project
pixi init
pixi add --channel https://prefix.dev/andmai/science --channel conda-forge mepgl
pixi run mepgl --version

For an existing Conda-compatible environment:

conda install -c https://prefix.dev/andmai/science -c conda-forge mepgl

The package includes the Python command, both native solver executables, and their CUDA runtime dependencies. It does not install an NVIDIA driver or compile code during a simulation.

Plotting is optional. For a PyPI installation, install mepgl[plot]. With the Conda package, add matplotlib, scipy, and tqdm to the environment when plots are needed.

MEPGL currently targets Linux x86-64 with an NVIDIA GPU and a driver compatible with CUDA 12. The initial support target is single precision on compute capability 8.9; double precision, thin-film mode, and the other architectures included in the package remain experimental.

Usage

A simulation is defined by a Python configuration file. The repository contains focused examples for:

• single-component vortex entry;
• two-component vortex entry;
• multiple vortices;
• multistep relaxation; and
• thin-film mode.

Run the smaller single-component example from a repository checkout:

mepgl run examples/single_component_vortex_entry.py

MEPGL selects mepgl-solver-f32 or mepgl-solver-f64 from the active environment according to the configuration's double_precision value. Use --solver PATH only to select a specific compatible executable.

Each run is stored in simulations/<simulation_name>/. By default, completed frames are post-processed into numerical data only. Pass --plots to also generate path_summary.pdf, path_parameterization.pdf, and one field image per path frame. To choose another working directory or post-process existing output:

mepgl run examples/single_component_vortex_entry.py --workdir /path/to/project
mepgl post single_component_vortex_entry --workdir /path/to/project --plots

Useful run options are:

• --no-init (-ni) to reuse existing input data;
• --reload-continue (-rc) to continue from the previous output;
• --plots to opt in to plot generation; and
• --no-post to skip automatic post-processing.

While a stage runs, the solver refreshes simulations/<simulation_name>/energy.csv with the current free energy of every frame. To watch it live:

python tools/rtanim.py <simulation_name> --workdir /path/to/project

Set fixed_endpoints = True in a simulation configuration to keep the first and last path frames unchanged while relaxing and redistributing the interior frames. The default is False.

max_iterations gives the hard iteration limit for each stage. Automatic convergence is disabled unless a convergence mapping is provided:

convergence = {
    "barrier_rtol": 2e-3,
    "barrier_atol": 1e-6,
    "path_rtol": 3e-2,
    "path_atol": 1e-6,
    "min_iterations": 25,
    "patience": 5,
}

These tolerances look loose on purpose. Each outer iteration redistributes the frames along the path, so both residuals settle onto a nonzero limit cycle instead of decaying: the RMS path displacement holds near 1.5e-2 of the path scale and the barrier rings at roughly 1e-3 of its value. That floor is a property of the method, not of the arithmetic - it is unchanged in double precision and unchanged when the frame count is doubled - so tolerances below it can never be satisfied and the stage will always stop at its iteration limit. Doubling the frame count does shrink the barrier ringing by about a factor of three, because the barrier is a maximum over frames; it leaves the path residual untouched.

Because the residuals only measure the change per iteration, they cannot distinguish a slow or metastable stretch of a path from a converged one. A path that stalls before rearranging - examples/multiple_vortices.py holds a plateau for about a hundred iterations - will report convergence well above its true barrier. Confirm against a fixed-iteration run before enabling criteria on a new configuration, and prefer a plain iteration limit when a path is known to stall.

A single mapping applies to every stage. A sequence aligned with F, max_iterations, and modes can contain a mapping or None for each stage. Existing configurations using iterations remain supported as a legacy alias for max_iterations; defining both is an error.

Convergence requires both the energy-barrier change and the gauge-invariant RMS path displacement to satisfy their mixed absolute and relative tolerances for patience consecutive iterations after min_iterations. The path metric combines condensate magnitudes, magnetic field, and currents; it excludes fixed endpoints. iterations/max_iterations remains the hard cap.

Enabled runs write simulations/<simulation_name>/convergence.json, including per-stage criteria, termination reasons, final status, and scalar iteration history. If an enabled stage reaches its cap or is stopped by the user before converging, MEPGL preserves its output and report but exits with an error.

Cartesian input arrays use NumPy spatial-axis order (Ny, Nx): x varies along the contiguous last axis and y along the leading axis. Path-dependent fields therefore have shape (F, Ny, Nx). StringBuilder accepts independent Nx, Ny, x_lim, and y_lim; the native solver derives both grid dimensions and spacings from x.npy and y.npy. Existing configurations that use the legacy (Nx, Ny) mesh orientation are transposed when their input files are created.

Use mepgl run --help and mepgl post --help for the complete command-line reference.

Development

Install the locked development environment and build the local CUDA solver:

git clone https://github.com/maiani/mepgl.git
cd mepgl
pixi install
pixi run build
pixi run run

pixi run build creates single- and double-precision executables under solver/build/cmake/release/. It does not copy duplicate binaries into the source directory.

The main checks are:

pixi run check
pixi run gpu-check

check compile-checks Python, runs pytest and host-side native tests, and builds the solver for compute capability 8.9. gpu-check runs and validates the small GPU smoke simulation, including native convergence and reporting.

Distribution artifacts are built locally with:

pixi run python-package
pixi run conda-package

The wheel and source distribution are written to build/packages/; the complete Conda package is written to build/conda/. The Python wheel contains only the frontend and therefore requires compatible solver executables from another source. None of these tasks publishes an artifact.

pixi run release-check runs the Python checks and builds both package formats. GPU qualification remains the separate pixi run gpu-check gate.

Citation

Please cite the repository and the relevant method paper:

• A. Benfenati, A. Maiani, F. N. Rybakov, and E. Babaev, Vortex nucleation barrier in superconductors beyond the Bean-Livingston approximation, Physical Review B 101, 220505 (2020).
• A. Maiani, A. Benfenati, and E. Babaev, Vortex nucleation barriers and stable fractional vortices near boundaries in multicomponent superconductors, Physical Review B 105, 224507 (2022).

Machine-readable citation metadata is available in CITATION.cff.

License

MEPGL is released under the MIT License.