# TNFR Python Engine
Canonical implementation of the Resonant Fractal Nature Theory (TNFR) for modelling structural
coherence. The engine seeds resonant nodes, applies structural operators, coordinates
ΔNFR/phase dynamics, and measures coherence metrics (C(t), Si, νf) without breaking the nodal
equation $\partial EPI/\partial t = \nu_f \cdot \Delta NFR(t)$.
## Snapshot
- **Operate:** build nodes with `tnfr.create_nfr`, execute trajectories via
`tnfr.structural.run_sequence`, and evolve dynamics with `tnfr.dynamics.run`.
- **Observe:** register metrics/trace callbacks to capture ΔNFR, C(t), Si, and structural
histories
for every run.
- **Extend:** rely on the canonical operator grammar and invariants before introducing new
utilities or telemetry.
## Quickstart
Install from PyPI (Python ≥ 3.9):
```bash
pip install tnfr
```
Then follow the [quickstart guide](docs/source/getting-started/quickstart.md) for Python and CLI
walkthroughs plus optional dependency caching helpers.
## CLI profiling helpers
Generate Sense Index and ΔNFR profiling artefacts directly from the CLI with the
``profile-pipeline`` subcommand. The helper reproduces the performance benchmark that
captures vectorised and fallback execution traces for the full pipeline:
```bash
tnfr profile-pipeline \
--nodes 120 --edge-probability 0.28 --loops 3 \
--si-chunk-sizes auto 48 --dnfr-chunk-sizes auto \
--si-workers auto --dnfr-workers auto \
--output-dir profiles/pipeline
```
The command writes ``.pstats`` and JSON summaries for each configuration/mode pair, making
it easy to inspect hot paths with :mod:`pstats`, Snakeviz, or downstream tooling.
## Documentation map
- [Documentation index](docs/source/home.md) — navigation hub for API chapters and examples.
- [API overview](docs/source/api/overview.md) — package map, invariants, and structural data flow.
- [Structural operators](docs/source/api/operators.md) — canonical grammar, key concepts, and typical
workflows.
- [Telemetry & utilities](docs/source/api/telemetry.md) — coherence metrics, trace capture, locking,
and helper facades.
- [Examples](docs/source/examples/README.md) — runnable scenarios, CLI artefacts, and token legend.
## Documentation build workflow
Netlify now renders the documentation with [Sphinx](https://www.sphinx-doc.org/) so MyST Markdown,
doctests, and notebooks share a single pipeline. Reproduce the hosted site locally as follows:
1. Create and activate a virtual environment (e.g. `python -m venv .venv && source .venv/bin/activate`).
2. Install the documentation toolchain and project extras:
`python -m pip install -r docs/requirements.txt && python -m pip install -e .[docs]`.
3. Execute the doctest suite with `sphinx-build -b doctest docs/source docs/_build/doctest` to ensure
structural snippets remain coherent.
4. Generate the HTML site with `make docs`, which wraps `sphinx-build -b html docs/source docs/_build/html`.
The Netlify build (`netlify.toml`) runs `python -m pip install -r docs/requirements.txt && make docs`
and publishes the resulting `docs/_build/html` directory, keeping the hosted documentation aligned with
local verification runs.
## Local development
Use the helper scripts to keep formatting aligned with the canonical configuration and to reproduce
the quality gate locally:
```bash
./scripts/format.sh # Apply Black and isort across src/, tests/, scripts/, and benchmarks/
./scripts/format.sh --check # Validate formatting without modifying files
./scripts/run_tests.sh # Execute the full QA battery (type checks, tests, coverage, linting)
```
The formatting helper automatically prefers `poetry run` when a Poetry environment is available and
falls back to `python -m` invocations so local runs mirror the tooling invoked in continuous
integration.
## Additional resources
- [ARCHITECTURE.md](ARCHITECTURE.md) — orchestration layers and invariant enforcement.
- [CONTRIBUTING.md](CONTRIBUTING.md) — QA battery (`scripts/run_tests.sh`) and review
expectations.
- [TNFR.pdf](TNFR.pdf) — theoretical background, structural operators, and paradigm glossary.
## Migration notes
- **Si dispersion keys:** Ensure graph payloads and configuration files use the canonical
``dSi_dphase_disp`` attribute for Si dispersion sensitivity before upgrading. The runtime now
raises :class:`ValueError` listing any unexpected sensitivity keys, and
:func:`tnfr.metrics.sense_index.compute_Si_node` rejects unknown keyword arguments.
- Refer to the [release notes](docs/source/releases.md#1100-si-dispersion-legacy-keys-removed) for
a migration snippet that rewrites stored graphs in place prior to running the new version.
## Licensing
Released under the [MIT License](LICENSE.md). Cite the TNFR paradigm when publishing research
or derived artefacts based on this engine.
Raw data
{
"_id": null,
"home_page": null,
"name": "tnfr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "TNFR, complex systems, fractals, resonance, networks, structural dynamics, structural analysis",
"author": "fmg",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b1/ba/25024e41bcfb00c13dc6bf988146e324a7624dcaf4ae5afd8e451c7c7f7d/tnfr-7.0.0.tar.gz",
"platform": null,
"description": "# TNFR Python Engine\r\n\r\nCanonical implementation of the Resonant Fractal Nature Theory (TNFR) for modelling structural\r\ncoherence. The engine seeds resonant nodes, applies structural operators, coordinates\r\n\u0394NFR/phase dynamics, and measures coherence metrics (C(t), Si, \u03bdf) without breaking the nodal\r\nequation $\\partial EPI/\\partial t = \\nu_f \\cdot \\Delta NFR(t)$.\r\n\r\n## Snapshot\r\n\r\n- **Operate:** build nodes with `tnfr.create_nfr`, execute trajectories via\r\n `tnfr.structural.run_sequence`, and evolve dynamics with `tnfr.dynamics.run`.\r\n- **Observe:** register metrics/trace callbacks to capture \u0394NFR, C(t), Si, and structural\r\n histories\r\n for every run.\r\n- **Extend:** rely on the canonical operator grammar and invariants before introducing new\r\n utilities or telemetry.\r\n\r\n## Quickstart\r\n\r\nInstall from PyPI (Python \u2265 3.9):\r\n\r\n```bash\r\npip install tnfr\r\n```\r\n\r\nThen follow the [quickstart guide](docs/source/getting-started/quickstart.md) for Python and CLI\r\nwalkthroughs plus optional dependency caching helpers.\r\n\r\n## CLI profiling helpers\r\n\r\nGenerate Sense Index and \u0394NFR profiling artefacts directly from the CLI with the\r\n``profile-pipeline`` subcommand. The helper reproduces the performance benchmark that\r\ncaptures vectorised and fallback execution traces for the full pipeline:\r\n\r\n```bash\r\ntnfr profile-pipeline \\\r\n --nodes 120 --edge-probability 0.28 --loops 3 \\\r\n --si-chunk-sizes auto 48 --dnfr-chunk-sizes auto \\\r\n --si-workers auto --dnfr-workers auto \\\r\n --output-dir profiles/pipeline\r\n```\r\n\r\nThe command writes ``.pstats`` and JSON summaries for each configuration/mode pair, making\r\nit easy to inspect hot paths with :mod:`pstats`, Snakeviz, or downstream tooling.\r\n\r\n## Documentation map\r\n\r\n- [Documentation index](docs/source/home.md) \u2014 navigation hub for API chapters and examples.\r\n- [API overview](docs/source/api/overview.md) \u2014 package map, invariants, and structural data flow.\r\n- [Structural operators](docs/source/api/operators.md) \u2014 canonical grammar, key concepts, and typical\r\n workflows.\r\n- [Telemetry & utilities](docs/source/api/telemetry.md) \u2014 coherence metrics, trace capture, locking,\r\n and helper facades.\r\n- [Examples](docs/source/examples/README.md) \u2014 runnable scenarios, CLI artefacts, and token legend.\r\n\r\n## Documentation build workflow\r\n\r\nNetlify now renders the documentation with [Sphinx](https://www.sphinx-doc.org/) so MyST Markdown,\r\ndoctests, and notebooks share a single pipeline. Reproduce the hosted site locally as follows:\r\n\r\n1. Create and activate a virtual environment (e.g. `python -m venv .venv && source .venv/bin/activate`).\r\n2. Install the documentation toolchain and project extras:\r\n `python -m pip install -r docs/requirements.txt && python -m pip install -e .[docs]`.\r\n3. Execute the doctest suite with `sphinx-build -b doctest docs/source docs/_build/doctest` to ensure\r\n structural snippets remain coherent.\r\n4. Generate the HTML site with `make docs`, which wraps `sphinx-build -b html docs/source docs/_build/html`.\r\n\r\nThe Netlify build (`netlify.toml`) runs `python -m pip install -r docs/requirements.txt && make docs`\r\nand publishes the resulting `docs/_build/html` directory, keeping the hosted documentation aligned with\r\nlocal verification runs.\r\n\r\n## Local development\r\n\r\nUse the helper scripts to keep formatting aligned with the canonical configuration and to reproduce\r\nthe quality gate locally:\r\n\r\n```bash\r\n./scripts/format.sh # Apply Black and isort across src/, tests/, scripts/, and benchmarks/\r\n./scripts/format.sh --check # Validate formatting without modifying files\r\n./scripts/run_tests.sh # Execute the full QA battery (type checks, tests, coverage, linting)\r\n```\r\n\r\nThe formatting helper automatically prefers `poetry run` when a Poetry environment is available and\r\nfalls back to `python -m` invocations so local runs mirror the tooling invoked in continuous\r\nintegration.\r\n\r\n## Additional resources\r\n\r\n- [ARCHITECTURE.md](ARCHITECTURE.md) \u2014 orchestration layers and invariant enforcement.\r\n- [CONTRIBUTING.md](CONTRIBUTING.md) \u2014 QA battery (`scripts/run_tests.sh`) and review\r\n expectations.\r\n- [TNFR.pdf](TNFR.pdf) \u2014 theoretical background, structural operators, and paradigm glossary.\r\n\r\n## Migration notes\r\n\r\n- **Si dispersion keys:** Ensure graph payloads and configuration files use the canonical\r\n ``dSi_dphase_disp`` attribute for Si dispersion sensitivity before upgrading. The runtime now\r\n raises :class:`ValueError` listing any unexpected sensitivity keys, and\r\n :func:`tnfr.metrics.sense_index.compute_Si_node` rejects unknown keyword arguments.\r\n- Refer to the [release notes](docs/source/releases.md#1100-si-dispersion-legacy-keys-removed) for\r\n a migration snippet that rewrites stored graphs in place prior to running the new version.\r\n\r\n## Licensing\r\n\r\nReleased under the [MIT License](LICENSE.md). Cite the TNFR paradigm when publishing research\r\nor derived artefacts based on this engine.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Modular structural-based dynamics on networks.",
"version": "7.0.0",
"project_urls": {
"GPT": "https://chatgpt.com/g/g-67abc78885a88191b2d67f94fd60dc97-tnfr-resonant-fractal-nature-theory",
"Homepage": "https://pypi.org/project/tnfr/",
"Repository": "https://github.com/fermga/TNFR-Python-Engine"
},
"split_keywords": [
"tnfr",
" complex systems",
" fractals",
" resonance",
" networks",
" structural dynamics",
" structural analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0bb98c946919e8fdc9f9054f46338e3de50abf40aa4d049a055628facb2c44e5",
"md5": "3878e99d5762f24dec2e67c6dfc6c59d",
"sha256": "63fc9479c9edd36b49d9672d29f3048b2d229cb6da2213b79a8585eab235e5d4"
},
"downloads": -1,
"filename": "tnfr-7.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3878e99d5762f24dec2e67c6dfc6c59d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 347910,
"upload_time": "2025-11-02T11:33:35",
"upload_time_iso_8601": "2025-11-02T11:33:35.483296Z",
"url": "https://files.pythonhosted.org/packages/0b/b9/8c946919e8fdc9f9054f46338e3de50abf40aa4d049a055628facb2c44e5/tnfr-7.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1ba25024e41bcfb00c13dc6bf988146e324a7624dcaf4ae5afd8e451c7c7f7d",
"md5": "1802f9d946ab34ed1a7ef6417223c3bd",
"sha256": "c65473880214a514d528a01ddea34e80a9c25497fa5fa9a47956baab5d2206e6"
},
"downloads": -1,
"filename": "tnfr-7.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1802f9d946ab34ed1a7ef6417223c3bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 277584,
"upload_time": "2025-11-02T11:33:42",
"upload_time_iso_8601": "2025-11-02T11:33:42.385535Z",
"url": "https://files.pythonhosted.org/packages/b1/ba/25024e41bcfb00c13dc6bf988146e324a7624dcaf4ae5afd8e451c7c7f7d/tnfr-7.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 11:33:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fermga",
"github_project": "TNFR-Python-Engine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tnfr"
}
JSON
