Metadata-Version: 2.4
Name: tfgt
Version: 0.1.0
Summary: Topological Free-energy Gradient Theory toolkit for fluid-topology computation with NS++ topological forcing.
Home-page: https://github.com/panguojun/tfgt
Author: Pan Guojun
Author-email: Pan Guojun <18858146@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/panguojun/tfgt
Project-URL: Repository, https://github.com/panguojun/tfgt
Project-URL: Documentation, https://github.com/panguojun/tfgt#readme
Project-URL: Bug Reports, https://github.com/panguojun/tfgt/issues
Keywords: fluid,topology,navier-stokes,thermodynamics,free-energy,scientific-computing,numpy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# TFGT

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

Core modeling identity:

```text
f_top = -lambda * grad(F_top)
```

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

```text
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

```bash
pip install tfgt
```

From source:

```bash
pip install .
```

## Quick Start

```python
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:

```bash
pip install -e .[dev]
```

Run tests:

```bash
pytest -q
```

Build package:

```bash
python -m build
```

Validate artifacts:

```bash
python -m twine check dist/*
```

Upload:

```bash
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.

