tfgt 0.1.0

Topological Free-energy Gradient Theory toolkit for fluid-topology computation with NS++ topological forcing.

TFGT

TFGT (tfgt) is a Python package for fluid-topology computation based on the Topological Free-energy Gradient Theory.

Core modeling identity:

f_top = -lambda * grad(F_top)

This equivalent topological force can be injected into an NS++ momentum model:

rho * Du/Dt = -grad(p) + div(tau) - lambda * grad(F_top)

Theory Snapshot

This package is initialized from the research note:

C:\Users\18858\Desktop\MD_2026-04-28_10-09-36_668.md

Canonical baseline parameters implemented here:

• lambda0 = 4*pi*alpha
• E0 = 0.026 eV

Installation

pip install tfgt

From source:

pip install .

Quick Start

import numpy as np
from tfgt import TFGTParameters, topological_force, nspp_rhs, topological_activity_index

# Build a synthetic free-energy field F_top on a 2D grid.
x = np.linspace(-1.0, 1.0, 64)
y = np.linspace(-1.0, 1.0, 64)
xx, yy = np.meshgrid(x, y, indexing="ij")
F_top = np.exp(-6.0 * (xx**2 + yy**2))

params = TFGTParameters()
force = topological_force(F_top, lambda_top=params.lambda0, spacing=(x[1] - x[0], y[1] - y[0]))

rho = 1.0
pressure_gradient = np.zeros_like(force)
tau_divergence = np.zeros_like(force)
velocity = np.zeros_like(force)

dudt = nspp_rhs(
    velocity=velocity,
    rho=rho,
    pressure_gradient=pressure_gradient,
    tau_divergence=tau_divergence,
    f_top=F_top,
    lambda_top=params.lambda0,
    spacing=(x[1] - x[0], y[1] - y[0]),
)

print("dudt shape:", dudt.shape)
print("TAI:", topological_activity_index(F_top, lambda_top=params.lambda0))

API

• TFGTParameters: canonical parameter container (alpha, lambda0, E0)
• gradient_nd, laplacian_nd: finite-difference scalar field operators
• topological_force: equivalent topology force from free-energy field
• nspp_acceleration, nspp_rhs: NS++ helper terms
• vorticity_2d, helicity_density_3d, enstrophy_2d, topological_activity_index

Build and Publish

Install dev tooling:

pip install -e .[dev]

Run tests:

pytest -q

Build package:

python -m build

Validate artifacts:

python -m twine check dist/*

Upload:

python -m twine upload dist/*

Scientific Scope

tfgt currently provides a computational core and reference utilities for fluid-topology workflows. It does not claim experimental validation by itself. Use this library together with your own data, calibration, and falsifiability protocols.

License

MIT License.