tfgt 0.3.1

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.1.

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

Complex Energy / Structural Topology Phase

The package also includes a reduced numerical model for the complex-energy extension of TFGT:

E_complex = E_free + i E_topo
F_complex = F_geo  + i F_topo

In this model:

• E_free is the real geometric/free-energy channel.
• E_topo is the imaginary structural-topology energy channel.
• F_geo acts in physical configuration space.
• F_topo acts in topology phase space.
• topology phase accumulates after a yield/activation threshold.
• sector transitions cross sector-dependent topology energy gaps.
• irreversible free-energy-to-topology-energy conversion produces entropy.

Minimal validation example:

import numpy as np
from tfgt import (
    ComplexEnergyConfig,
    ComplexEnergyState,
    StructuralTopologySector,
    simulate_complex_energy,
)

sectors = (
    StructuralTopologySector("elastic", phase_threshold=0.25, energy_gap=0.0),
    StructuralTopologySector("plastic", phase_threshold=0.75, energy_gap=1.5),
)
cfg = ComplexEnergyConfig(
    yield_displacement=1.0,
    topology_coupling=3.0,
    dissipation_fraction=0.25,
    dt=0.1,
)

history = simulate_complex_energy(
    ComplexEnergyState(displacement=np.array([0.0])),
    sectors,
    cfg,
    steps=25,
    external_displacement_rate=np.array([1.0]),
)

print(history[-1].energy.sector)
print(history[-1].energy.complex_value)
print(history[-1].energy.entropy)

The corresponding tests verify that the topology channel is inactive before yield, phase accumulates after activation, sector jumps cross topology energy gaps, and entropy production is nonnegative.

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.