tfgt 0.1.0__tar.gz

tfgt-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Pan Guojun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

tfgt-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include tfgt *.py
+

tfgt-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+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.
+

tfgt-0.1.0/README.md

@@ -0,0 +1,125 @@
+# 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.
+

tfgt-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tfgt"
+version = "0.1.0"
+description = "Topological Free-energy Gradient Theory toolkit for fluid-topology computation with NS++ topological forcing."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "Pan Guojun", email = "18858146@qq.com" }
+]
+keywords = [
+  "fluid",
+  "topology",
+  "navier-stokes",
+  "thermodynamics",
+  "free-energy",
+  "scientific-computing",
+  "numpy"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Physics",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent"
+]
+dependencies = [
+  "numpy>=1.22"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.0",
+  "pytest>=8.0.0",
+  "twine>=5.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/panguojun/tfgt"
+Repository = "https://github.com/panguojun/tfgt"
+Documentation = "https://github.com/panguojun/tfgt#readme"
+"Bug Reports" = "https://github.com/panguojun/tfgt/issues"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["tfgt*"]

tfgt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tfgt-0.1.0/setup.py

@@ -0,0 +1,24 @@
+from setuptools import setup, find_packages
+
+
+setup(
+    name="tfgt",
+    version="0.1.0",
+    packages=find_packages(),
+    include_package_data=True,
+    description=(
+        "Topological Free-energy Gradient Theory toolkit for fluid-topology "
+        "computation with NS++ topological forcing."
+    ),
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="Pan Guojun",
+    author_email="18858146@qq.com",
+    url="https://github.com/panguojun/tfgt",
+    python_requires=">=3.9",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+        "Topic :: Scientific/Engineering :: Physics",
+    ],
+)

tfgt-0.1.0/tests/test_tfgt_core.py

@@ -0,0 +1,41 @@
+import numpy as np
+
+from tfgt import TFGTParameters, nspp_rhs, topological_force, topological_activity_index
+
+
+def test_topological_force_shape() -> None:
+    x = np.linspace(-1.0, 1.0, 32)
+    y = np.linspace(-1.0, 1.0, 24)
+    xx, yy = np.meshgrid(x, y, indexing="ij")
+    f_top = xx**2 + yy**2
+    force = topological_force(f_top, spacing=(x[1] - x[0], y[1] - y[0]))
+    assert force.shape == (2, 32, 24)
+
+
+def test_nspp_rhs_shape() -> None:
+    n = 16
+    f_top = np.random.default_rng(123).normal(size=(n, n))
+    velocity = np.zeros((2, n, n), dtype=float)
+    zero = np.zeros_like(velocity)
+    params = TFGTParameters()
+
+    rhs = nspp_rhs(
+        velocity=velocity,
+        rho=1.0,
+        pressure_gradient=zero,
+        tau_divergence=zero,
+        f_top=f_top,
+        lambda_top=params.lambda0,
+        spacing=1.0,
+    )
+    assert rhs.shape == velocity.shape
+
+
+def test_topological_activity_index_positive() -> None:
+    x = np.linspace(-2.0, 2.0, 20)
+    y = np.linspace(-2.0, 2.0, 20)
+    xx, yy = np.meshgrid(x, y, indexing="ij")
+    f_top = np.exp(-(xx * xx + yy * yy))
+    value = topological_activity_index(f_top)
+    assert value > 0.0
+

tfgt-0.1.0/tfgt/__init__.py

@@ -0,0 +1,36 @@
+"""
+TFGT: Topological Free-energy Gradient Theory toolkit.
+
+Core equation implemented in this package:
+    f_top = -lambda * grad(F_top)
+"""
+
+from .constants import TFGTParameters, alpha_default, lambda0_default, e0_default_ev
+from .fields import gradient_nd, laplacian_nd
+from .forces import topological_force
+from .nspp import nspp_acceleration, nspp_rhs
+from .metrics import (
+    vorticity_2d,
+    helicity_density_3d,
+    enstrophy_2d,
+    topological_activity_index,
+)
+
+__all__ = [
+    "TFGTParameters",
+    "alpha_default",
+    "lambda0_default",
+    "e0_default_ev",
+    "gradient_nd",
+    "laplacian_nd",
+    "topological_force",
+    "nspp_acceleration",
+    "nspp_rhs",
+    "vorticity_2d",
+    "helicity_density_3d",
+    "enstrophy_2d",
+    "topological_activity_index",
+]
+
+__version__ = "0.1.0"
+

tfgt-0.1.0/tfgt/constants.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+alpha_default: float = 1.0 / 137.035999084
+e0_default_ev: float = 0.026
+lambda0_default: float = 4.0 * math.pi * alpha_default
+
+EV_TO_J = 1.602176634e-19
+
+
+@dataclass(frozen=True)
+class TFGTParameters:
+    """
+    Canonical TFGT parameters.
+
+    The baseline matches the initial research note:
+      lambda_0 ~ 4*pi*alpha
+      E0 = 0.026 eV
+    """
+
+    alpha: float = alpha_default
+    e0_ev: float = e0_default_ev
+
+    @property
+    def lambda0(self) -> float:
+        return 4.0 * math.pi * self.alpha
+
+    @property
+    def e0_joule(self) -> float:
+        return self.e0_ev * EV_TO_J
+

tfgt-0.1.0/tfgt/fields.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Iterable, Sequence
+import numpy as np
+
+ArrayLike = np.ndarray
+
+
+def _normalize_spacing(ndim: int, spacing: float | Sequence[float]) -> tuple[float, ...]:
+    if isinstance(spacing, (int, float)):
+        return (float(spacing),) * ndim
+    s = tuple(float(v) for v in spacing)
+    if len(s) != ndim:
+        raise ValueError(f"spacing length ({len(s)}) must equal ndim ({ndim})")
+    return s
+
+
+def gradient_nd(field: ArrayLike, spacing: float | Sequence[float] = 1.0) -> list[np.ndarray]:
+    """
+    Return grad(field) for an N-D scalar field using finite differences.
+    """
+    arr = np.asarray(field, dtype=float)
+    ds = _normalize_spacing(arr.ndim, spacing)
+    return list(np.gradient(arr, *ds, edge_order=2))
+
+
+def laplacian_nd(field: ArrayLike, spacing: float | Sequence[float] = 1.0) -> np.ndarray:
+    """
+    Return the N-D Laplacian sum_i d2(field)/dx_i^2 from central differences.
+    """
+    arr = np.asarray(field, dtype=float)
+    ds = _normalize_spacing(arr.ndim, spacing)
+    grad = np.gradient(arr, *ds, edge_order=2)
+    lap = np.zeros_like(arr, dtype=float)
+    for axis, (g, d) in enumerate(zip(grad, ds)):
+        dgi = np.gradient(g, d, axis=axis, edge_order=2)
+        lap += dgi
+    return lap
+

tfgt-0.1.0/tfgt/forces.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Sequence
+import numpy as np
+
+from .constants import lambda0_default
+from .fields import gradient_nd
+
+
+def topological_force(
+    f_top: np.ndarray,
+    *,
+    lambda_top: float = lambda0_default,
+    spacing: float | Sequence[float] = 1.0,
+) -> np.ndarray:
+    """
+    Compute equivalent topological force field:
+        f = -lambda_top * grad(F_top)
+
+    Returns an array with shape (ndim, ...).
+    """
+    grad_f = gradient_nd(f_top, spacing=spacing)
+    return -float(lambda_top) * np.stack(grad_f, axis=0)
+

tfgt-0.1.0/tfgt/metrics.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Sequence
+import numpy as np
+
+from .fields import gradient_nd
+from .forces import topological_force
+from .constants import lambda0_default
+
+
+def vorticity_2d(velocity: np.ndarray, spacing: float | Sequence[float] = 1.0) -> np.ndarray:
+    """
+    Return scalar vorticity for 2D velocity field [u, v]:
+        omega_z = dv/dx - du/dy
+    """
+    vel = np.asarray(velocity, dtype=float)
+    if vel.ndim != 3 or vel.shape[0] != 2:
+        raise ValueError("velocity must have shape (2, nx, ny)")
+
+    u, v = vel[0], vel[1]
+    if isinstance(spacing, (int, float)):
+        dx = dy = float(spacing)
+    else:
+        dx, dy = spacing
+
+    du_dy = np.gradient(u, dy, axis=1, edge_order=2)
+    dv_dx = np.gradient(v, dx, axis=0, edge_order=2)
+    return dv_dx - du_dy
+
+
+def helicity_density_3d(velocity: np.ndarray, spacing: float | Sequence[float] = 1.0) -> np.ndarray:
+    """
+    Return helicity density h = u . (curl u) for 3D velocity field [u, v, w].
+    """
+    vel = np.asarray(velocity, dtype=float)
+    if vel.ndim != 4 or vel.shape[0] != 3:
+        raise ValueError("velocity must have shape (3, nx, ny, nz)")
+
+    u, v, w = vel
+    if isinstance(spacing, (int, float)):
+        dx = dy = dz = float(spacing)
+    else:
+        dx, dy, dz = spacing
+
+    du_dy = np.gradient(u, dy, axis=1, edge_order=2)
+    du_dz = np.gradient(u, dz, axis=2, edge_order=2)
+    dv_dx = np.gradient(v, dx, axis=0, edge_order=2)
+    dv_dz = np.gradient(v, dz, axis=2, edge_order=2)
+    dw_dx = np.gradient(w, dx, axis=0, edge_order=2)
+    dw_dy = np.gradient(w, dy, axis=1, edge_order=2)
+
+    curl_x = dw_dy - dv_dz
+    curl_y = du_dz - dw_dx
+    curl_z = dv_dx - du_dy
+    return u * curl_x + v * curl_y + w * curl_z
+
+
+def enstrophy_2d(velocity: np.ndarray, spacing: float | Sequence[float] = 1.0) -> float:
+    """
+    Return integral-like enstrophy proxy in 2D:
+        E = 0.5 * mean(omega^2)
+    """
+    omega = vorticity_2d(velocity, spacing=spacing)
+    return 0.5 * float(np.mean(omega * omega))
+
+
+def topological_activity_index(
+    f_top: np.ndarray,
+    *,
+    lambda_top: float = lambda0_default,
+    spacing: float | Sequence[float] = 1.0,
+) -> float:
+    """
+    A compact scalar intensity for topology-driven forcing:
+        TAI = mean(||-lambda*grad(F_top)||_2)
+    """
+    force = topological_force(f_top, lambda_top=lambda_top, spacing=spacing)
+    mag = np.linalg.norm(force, axis=0)
+    return float(np.mean(mag))
+

tfgt-0.1.0/tfgt/nspp.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Sequence
+import numpy as np
+
+from .forces import topological_force
+
+
+def nspp_acceleration(
+    rho: float | np.ndarray,
+    pressure_gradient: np.ndarray,
+    tau_divergence: np.ndarray,
+    f_top: np.ndarray,
+    *,
+    lambda_top: float,
+    spacing: float | Sequence[float] = 1.0,
+) -> np.ndarray:
+    """
+    NS++ acceleration term:
+        Du/Dt = (-grad(p) + div(tau) - lambda*grad(F_top)) / rho
+
+    The first axis of pressure_gradient and tau_divergence is vector dimension.
+    """
+    rho_arr = np.asarray(rho, dtype=float)
+    p_grad = np.asarray(pressure_gradient, dtype=float)
+    tau_div = np.asarray(tau_divergence, dtype=float)
+    f_eq = topological_force(f_top, lambda_top=lambda_top, spacing=spacing)
+    if p_grad.shape != tau_div.shape or p_grad.shape != f_eq.shape:
+        raise ValueError(
+            "pressure_gradient, tau_divergence and topological force must share shape"
+        )
+    return (-p_grad + tau_div + f_eq) / rho_arr
+
+
+def nspp_rhs(
+    velocity: np.ndarray,
+    rho: float | np.ndarray,
+    pressure_gradient: np.ndarray,
+    tau_divergence: np.ndarray,
+    f_top: np.ndarray,
+    *,
+    lambda_top: float,
+    spacing: float | Sequence[float] = 1.0,
+) -> np.ndarray:
+    """
+    Simple explicit RHS helper:
+        dU/dt = NS++ acceleration
+
+    This function is solver-agnostic and intended to be plugged into user time
+    integrators (Euler/RK/IMEX/etc.).
+    """
+    _ = np.asarray(velocity, dtype=float)
+    return nspp_acceleration(
+        rho=rho,
+        pressure_gradient=pressure_gradient,
+        tau_divergence=tau_divergence,
+        f_top=f_top,
+        lambda_top=lambda_top,
+        spacing=spacing,
+    )
+

tfgt-0.1.0/tfgt.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+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.
+

tfgt-0.1.0/tfgt.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+tests/test_tfgt_core.py
+tfgt/__init__.py
+tfgt/constants.py
+tfgt/fields.py
+tfgt/forces.py
+tfgt/metrics.py
+tfgt/nspp.py
+tfgt.egg-info/PKG-INFO
+tfgt.egg-info/SOURCES.txt
+tfgt.egg-info/dependency_links.txt
+tfgt.egg-info/requires.txt
+tfgt.egg-info/top_level.txt

tfgt-0.1.0/tfgt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tfgt-0.1.0/tfgt.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy>=1.22
+
+[dev]
+build>=1.2.0
+pytest>=8.0.0
+twine>=5.0.0

tfgt-0.1.0/tfgt.egg-info/top_level.txt

@@ -0,0 +1 @@
+tfgt