Metadata-Version: 2.4
Name: tfgt
Version: 0.3.1
Summary: Topological Free-energy Gradient Theory toolkit for topology-force, topology optimization, and topological free-gradient solving.
Home-page: https://github.com/panguojun/tfgt
Author: Pan Guojun
Author-email: Pan Guojun <18858146@qq.com>
License: 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,optimization,layout,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.

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:

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

used in NS++ momentum form:

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

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

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

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

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

## Topological Free Gradient Solver

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

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

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

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

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

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

## External Testing

Run black-box validation package:

```bash
python external_tests/run_external_validation.py
```

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

Topology optimization quickstart:

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