tfgt 0.3.0

Topological Free-energy Gradient Theory toolkit for topology-force, topology optimization, and topological free-gradient solving.

TFGT

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

Current release: 0.3.0.

Vision and Positioning

This project is positioned as a computational extension to Navier-Stokes, not a replacement.

We keep the classical conservation structure and inject one additional, explicit topology-force channel:

f_top = -lambda0 * grad(F_top)

used in NS++ momentum form:

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

At API level, users only need model parameters and fields:

• lambda0: topology-force coupling factor
• E0: baseline energy scale for cross-scale parameterization
• F_top: topological free-energy field

lambda0 can be supplied directly (its CFUT origin can remain hidden in engineering workflows), and E0 can be used directly as a fixed baseline from particle-mass research.

Core modeling identity:

f_top = -lambda0 * grad(F_top)

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

rho * Du/Dt = -grad(p) + div(tau) - lambda0 * 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

Practical Scope

The library targets practical NS-based macroscopic physics and engineering:

• Aerodynamics and flow-control analysis
• High-viscosity/non-Newtonian regimes (magma, asphalt, similar media)
• Friction/interface interpretation under topology-gradient correction
• Topology optimization where grad(F_top) is used as driving signal
• Semantic-to-geometry solving where semantic relations are compiled into topological free energy and solved by -lambda * grad(F_top)
• Engineering equipment spatial layout optimization with occupancy, connection-topology, access, load, and obstacle constraints

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))

Topological Free Gradient Solver

TopologicalFreeGradientSolver is the focused solver kernel for converting semantic constraints into geometric updates through TFGT:

semantic constraints -> F_top(q) -> -lambda * grad(F_top) -> geometry update

from tfgt import (
    SemanticGeometryConfig,
    SemanticGeometryConstraint,
    TopologicalFreeGradientSolver,
)

solver = TopologicalFreeGradientSolver(
    constraints=(
        SemanticGeometryConstraint("separate", "train_a", "train_b", distance=8.0, weight=2.0),
        SemanticGeometryConstraint("inside", "panel", "control_zone", weight=3.0),
    ),
    zones={
        "control_zone": ((20.0, 0.0, 0.0), (30.0, 10.0, 10.0)),
    },
    config=SemanticGeometryConfig(step_size=0.4, max_iters=80, lambda_top=1.0),
)

result = solver.solve(
    {
        "train_a": (5.0, 1.0, 5.0),
        "train_b": (8.0, 1.0, 5.0),
        "panel": (10.0, 1.0, 5.0),
    }
)

print(result.final_energy)
print(result.positions)

See docs/TOPOLOGICAL_FREE_GRADIENT_SOLVER.md for the solver boundary and API details.

API

• TFGTParameters: canonical parameter container (alpha, lambda0, E0)
• TFGTModel: high-level interface for NS++ RHS, Euler stepping, simulation loop
• TopologyOptimizer: topology-force-driven optimization solver
• TopologicalFreeGradientSolver: semantic constraints to geometry through F_top(q) and -lambda * grad(F_top)
• SemanticGeometryConstraint, SemanticGeometryConfig: primitives for the topological free-gradient solver
• layout_free_energy, layout_free_energy_gradient: practical layout objective/gradient for topology optimization
• build_free_energy_field: compose F_top from temperature/concentration/phase
• build_flow_free_energy_field: compose F_top from velocity/pressure flow observations
• 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
• compare_baseline_vs_topology: scalar diagnostics for external validation
• SpatialLayoutOptimizer: 2D equipment layout optimizer for engineering spaces
• LayoutDomain, Equipment, LayoutConnection: layout problem definitions

Dynamic topology optimization:

• TopologyOptimizer.optimize_dynamic: recompute physical gradients from the current design state each iteration
• normalize_design_gradient: RMS-normalize external physics gradients before topology-force updates
• blended_topology_gradient: blend geometric baseline gradients with FEA/flow/sensor-derived physical gradients

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/*

External Testing

Run black-box validation package:

python external_tests/run_external_validation.py

See outputs and report format in external_tests/README.md.

Topology optimization quickstart:

python examples/topo_opt_quickstart.py

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.

Engineering/scientific boundary:

• tfgt is solver-agnostic and intended for integration into existing CFD tools.
• Claims should be benchmarked, calibrated, and falsifiable.
• The package focuses on code-ready modeling, not standalone theoretical proof.

Philosophy (Chinese)

See docs/PHILOSOPHY_zh-CN.md for the full Chinese statement.

License

MIT License.