tnfr 4.5.2__tar.gz → 7.0.0__tar.gz

{tnfr-4.5.2 → tnfr-7.0.0}/LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2025 TNFR - Teoría de la naturaleza fractral resonante
+Copyright (c) 2025 TNFR – Resonant Fractal Nature Theory
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

tnfr-7.0.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: tnfr
+Version: 7.0.0
+Summary: Modular structural-based dynamics on networks.
+Author: fmg
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/tnfr/
+Project-URL: Repository, https://github.com/fermga/TNFR-Python-Engine
+Project-URL: GPT, https://chatgpt.com/g/g-67abc78885a88191b2d67f94fd60dc97-tnfr-resonant-fractal-nature-theory
+Keywords: TNFR,complex systems,fractals,resonance,networks,structural dynamics,structural analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: networkx>=2.6
+Requires-Dist: cachetools>=5
+Requires-Dist: typing-extensions>=4.4; python_version < "3.10"
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.24; extra == "numpy"
+Provides-Extra: jax
+Requires-Dist: jax>=0.4; extra == "jax"
+Provides-Extra: torch
+Requires-Dist: torch>=2.1; extra == "torch"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Provides-Extra: orjson
+Requires-Dist: orjson>=3; extra == "orjson"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == "viz"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: nbsphinx>=0.9; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == "docs"
+Requires-Dist: ipykernel>=6; extra == "docs"
+Requires-Dist: nbconvert>=7.16; extra == "docs"
+Requires-Dist: pypandoc-binary>=1.14; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-benchmark>=4; extra == "test"
+Requires-Dist: pydocstyle>=6; extra == "test"
+Requires-Dist: coverage>=7; extra == "test"
+Requires-Dist: hypothesis>=6; extra == "test"
+Requires-Dist: hypothesis-networkx>=0.3; extra == "test"
+Requires-Dist: flake8>=5; extra == "test"
+Requires-Dist: flake8-pyproject>=1.2; extra == "test"
+Requires-Dist: vulture>=2; extra == "test"
+Requires-Dist: matplotlib>=3.7; extra == "test"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.8; extra == "typecheck"
+Requires-Dist: networkx-stubs>=0.0.1; extra == "typecheck"
+Requires-Dist: types-cachetools>=6.0.0.0; extra == "typecheck"
+Requires-Dist: numpy>=1.24; extra == "typecheck"
+Provides-Extra: release
+Requires-Dist: python-semantic-release<11,>=10.4; extra == "release"
+Requires-Dist: setuptools-scm<9,>=8; extra == "release"
+Requires-Dist: build>=1; extra == "release"
+Requires-Dist: towncrier>=23; extra == "release"
+Dynamic: license-file
+
+# 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.

tnfr-7.0.0/README.md

@@ -0,0 +1,106 @@
+# 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.

tnfr-7.0.0/pyproject.toml

@@ -0,0 +1,181 @@
+[project]
+name = "tnfr"
+dynamic = ["version"]
+description = "Modular structural-based dynamics on networks."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "fmg" }]
+keywords = [
+  "TNFR", "complex systems", "fractals", "resonance", 
+  "networks", "structural dynamics", 
+  "structural analysis"
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Topic :: Scientific/Engineering :: Mathematics"
+]
+dependencies = [
+  "networkx>=2.6",
+  "cachetools>=5",
+  "typing-extensions>=4.4; python_version < \"3.10\"",
+]
+
+[project.optional-dependencies]
+numpy = ["numpy>=1.24"]
+jax = ["jax>=0.4"]
+torch = ["torch>=2.1"]
+yaml = ["pyyaml>=6.0"]
+orjson = ["orjson>=3"]
+viz = ["matplotlib>=3.7"]
+docs = [
+  "sphinx>=7.2",
+  "sphinx-autodoc-typehints>=1.25",
+  "myst-parser>=2.0",
+  "nbsphinx>=0.9",
+  "sphinx-rtd-theme>=1.3",
+  "sphinxcontrib-mermaid>=0.9",
+  "ipykernel>=6",
+  "nbconvert>=7.16",
+  "pypandoc-binary>=1.14",
+]
+test = [
+  "pytest>=7",
+  "pytest-benchmark>=4",
+  "pydocstyle>=6",
+  "coverage>=7",
+  "hypothesis>=6",
+  "hypothesis-networkx>=0.3",
+  "flake8>=5",
+  "flake8-pyproject>=1.2",
+  "vulture>=2",
+  "matplotlib>=3.7",
+]
+typecheck = [
+  "mypy>=1.8",
+  "networkx-stubs>=0.0.1",
+  "types-cachetools>=6.0.0.0",
+  "numpy>=1.24",
+]
+release = [
+  "python-semantic-release>=10.4,<11",
+  "setuptools-scm>=8,<9",
+  "build>=1",
+  "towncrier>=23",
+]
+
+[project.scripts]
+tnfr = "tnfr.cli:main"
+
+[project.urls]
+Homepage = "https://pypi.org/project/tnfr/"
+Repository = "https://github.com/fermga/TNFR-Python-Engine"
+GPT = "https://chatgpt.com/g/g-67abc78885a88191b2d67f94fd60dc97-tnfr-resonant-fractal-nature-theory"
+
+[tool.setuptools.package-data]
+tnfr = ["py.typed", "schemas/*.json"]
+
+[tool.setuptools_scm]
+tag_regex = '^v(?P<version>[0-9]+\.[0-9]+\.[0-9]+)$'
+local_scheme = "no-local-version"
+write_to = "src/tnfr/_generated_version.py"
+
+[tool.semantic_release]
+version_source = "tag"
+commit_parser = "conventional"
+allow_zero_version = false
+major_on_zero = false
+tag_format = "v{version}"
+
+[tool.semantic_release.branches.main]
+match = "^main$"
+prerelease = false
+
+[tool.semantic_release.changelog]
+template_dir = "meta/semantic_release/templates"
+mode = "update"
+changelog_file = ""
+
+[tool.semantic_release.changelog.default_templates]
+mask_initial_release = true
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat", "structure"]
+patch_tags = ["fix", "perf", "refactor", "docs", "test", "build", "ci", "style", "chore"]
+other_allowed_tags = ["revert", "docs", "test", "build", "ci", "style", "refactor", "perf", "chore"]
+allowed_tags = ["feat", "fix", "perf", "refactor", "docs", "test", "build", "ci", "style", "chore", "structure", "revert"]
+default_bump_level = 0
+parse_squash_commits = true
+ignore_merge_commits = true
+
+[tool.black]
+line-length = 88
+target-version = ["py39", "py310", "py311", "py312"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+skip = ["benchmarks"]
+
+[tool.flake8]
+max-line-length = 88
+ignore = ["E501", "W503"]
+exclude = ["benchmarks/"]
+
+[tool.pydocstyle]
+convention = "numpy"
+add-ignore = [
+  "D202",  # Allow blank line after docstring where needed for readability.
+]
+
+[tool.tnfr.language_check]
+exclude = [
+  "TNFR.pdf",
+  "benchmarks/**/*.pdf",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-m 'not slow' --benchmark-skip"
+markers = [
+  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+  "benchmarks: run with 'pytest benchmarks --benchmark-only' to execute the benchmark suite",
+  "stress: high-load deterministic stress coverage (select with '-m \"stress\"')",
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_configs = true
+warn_return_any = false
+no_implicit_optional = false
+strict_equality = false
+disallow_any_unimported = false
+show_error_codes = true
+follow_imports = "skip"
+allow_redefinition = true
+allow_untyped_defs = false
+allow_untyped_calls = false
+allow_untyped_globals = false
+
+[[tool.mypy.overrides]]
+module = ["networkx", "networkx.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["yaml", "yaml.*"]
+ignore_missing_imports = true
+
+
+[build-system]
+requires = ["setuptools>=78.1.1", "wheel", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"