tfgt 1.0.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: 1.0.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 as an effective topology-force coupling 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

Research Status

The bundled NS++ / NSPP research reproduction module tfgt.research_nspp accompanies a manuscript currently under review at Physics of Fluids (POF). The package provides reproducible code, figures, and numerical diagnostics for the submitted topological-state closure experiments. It should be cited and interpreted as under-review research software, not as a formally accepted publication.

The research module can be run with:

python -m tfgt.research_nspp --output ./demo_outputs

or, after installation:

tfgt-research-nspp --output ./demo_outputs

The core claim boundary is intentionally narrow: the module provides reproducible evidence for a reduced helicity/topological-sector closure and its diagnostic value on controlled vortex-state tasks. It does not claim to be a universal Navier-Stokes replacement, a production DNS solver, or a completed event-level vortex-reconnection predictor.

Reviewer Reproduction Guide

For external reviewers of the POF under-review manuscript, the recommended workflow is to install the package in a clean Python environment and run the bundled NSPP reproduction entry point.

Install from PyPI:

python -m pip install tfgt

Install a specific review version:

python -m pip install "tfgt==1.0.0"

Verify the installed version:

python -c "import tfgt; print(tfgt.__version__)"

Run the NSPP reproduction demo:

python -m tfgt.research_nspp --output ./nspp_review_outputs

Equivalent console command:

tfgt-research-nspp --output ./nspp_review_outputs

For a fast installation and reproduction smoke test, use the quick reviewer script from the source distribution or repository:

python tools/nspp_quick_review_test.py

This quick script runs a short subset of the NSPP reproduction scripts and writes outputs to ./nspp_quick_review_outputs by default. It is intended to validate import, execution, report generation, and core PNG/CSV output generation before running slower diagnostics.

Optional explicit output directory:

python tools/nspp_quick_review_test.py --output ./nspp_quick_review_outputs

Expected outputs include:

• NSPP_demo_run_report.md: script-by-script pass/fail status and raw stdout
• NSPP_visual_dashboard.png: dashboard of the core visual evidence
• POF_NS_topological_consistency_2026-05-07/figures/...: generated figures, CSV summaries, and Markdown summaries from individual reproduction scripts

Minimal Python import check:

import tfgt
from tfgt.research_nspp.run_demo import main

print(tfgt.__version__)
print(callable(main))

Programmatic reduced NS++ API example:

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

n = 32
x = np.linspace(-1.0, 1.0, n)
xx, yy = np.meshgrid(x, x, indexing="ij")
f_top = np.exp(-6.0 * (xx * xx + yy * yy))
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=x[1] - x[0],
)

print(rhs.shape)
print(topological_activity_index(f_top, lambda_top=params.lambda0))

The dynamic-stall audit optionally uses external validation data. If a reviewer has the dataset, set:

export STALL_VALIDATION_DATA_ROOT=/path/to/stall_validation

On Windows PowerShell:

$env:STALL_VALIDATION_DATA_ROOT="D:\Research\ResearchData\derived\stall_validation"

If the dataset is unavailable, the rest of the synthetic and reduced-observable reproduction scripts still run and the report records the corresponding audit status.

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

Package Structure

The public top-level imports remain available from tfgt, while the source is organized by functional area:

• tfgt.core: constants, field operators, topology force, metrics, validation
• tfgt.flow: NS++ RHS helpers, helicity-sector closure, flow model
• tfgt.energy: free-energy builders and complex-energy state model
• tfgt.optimization: topology optimization objectives and solvers
• tfgt.layout: 2D/3D equipment layout, PHG export, orthogonal routing
• tfgt.geometry: semantic-to-geometry free-gradient solvers
• tfgt.research_nspp: bundled NS++/NSPP reproduction scripts for the POF under-review manuscript

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.
• The bundled tfgt.research_nspp module is tied to a POF under-review manuscript and should not be represented as a formally published result until the review process is complete.

Philosophy (Chinese)

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

License

MIT License.