TNFR Python Engine Contributing to TNFR
Version 0.0.2 · DOI 10.5281/zenodo.17764207 · Updated 2025-11-30 Source CONTRIBUTING.md

Contributing to TNFR

Version: 0.0.1
Status: Complete theoretical framework with Universal Tetrahedral Correspondence
Authority: Canonical constants derived from TNFR theory
Quality: Production-ready with comprehensive test coverage

This document provides guidelines for contributing to the TNFR (Resonant Fractal Nature Theory) project. TNFR constitutes a computational framework for modeling complex systems through coherent patterns and resonance dynamics.

Mathematical Foundation Requirement

All contributions must maintain theoretical consistency. Requirements:

Table of Contents

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors, regardless of background, identity, or experience level.

Our Standards

Expected behavior:

Unacceptable behavior:

Enforcement

Instances of unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated promptly and fairly.

Getting Started

Prerequisites

Development Setup

# Install from PyPI (stable release)
pip install tnfr[viz,dev]

# Or clone for development
git clone https://github.com/fermga/TNFR-Python-Engine.git
cd TNFR-Python-Engine
pip install -e .[dev]

# Verify installation
python -c "from tnfr.constants.canonical import *; print(f'φ={PHI:.6f}, γ={GAMMA:.6f}')"

Canonical Constants Framework

All development must utilize theoretically derived canonical constants:

from tnfr.constants.canonical import *

# Correct: Use canonical constants
threshold = MIN_BUSINESS_COHERENCE  # (e×φ)/(π+e) ≈ 0.751

# Incorrect: Arbitrary numerical values
threshold = 0.75  # Lacks theoretical foundation

Additional Requirements

Development Environment

  1. Fork and clone the repository:

bash git clone https://github.com/YOUR_USERNAME/TNFR-Python-Engine.git cd TNFR-Python-Engine

  1. Create a virtual environment:

bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

  1. Install in development mode:

bash pip install -e ".[dev-minimal]"

  1. Install pre-commit hooks (optional but recommended):

bash pre-commit install

  1. Verify installation:

bash pytest tests/examples/test_u6_sequential_demo.py

Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Branch naming conventions:

2. Make Your Changes

3. Test Your Changes

# Run smoke tests (fast validation)
make smoke-tests  # Unix/Linux
.\make.cmd smoke-tests  # Windows

# Run full test suite
pytest

# Check code quality
ruff check src/
mypy src/tnfr/

3a. Phase 3 Structural Instrumentation

If adding validation, health, or telemetry logic:

Telemetry additions must:

Performance guardrails:

4. Update Documentation

5. Submit a Pull Request

See Pull Request Process below.

TNFR Principles

Before contributing, familiarize yourself with AGENTS.md - the canonical guide for TNFR development.

Core Principles

  1. Physics First: Every feature must derive from TNFR physics
  2. No Arbitrary Choices: All decisions traceable to nodal equation or invariants
  3. Coherence Over Convenience: Preserve theoretical integrity even if code is harder
  4. Reproducibility Always: Every simulation must be reproducible
  5. Document the Chain: Theory → Math → Code → Tests

The 6 Canonical Invariants

All contributions must preserve these invariants:

  1. Nodal Equation Integrity - EPI evolution via ∂EPI/∂t = νf · ΔNFR(t) only
  2. Phase-Coherent Coupling - Resonance requires |φᵢ - φⱼ| ≤ Δφ_max verification
  3. Multi-Scale Fractality - Operational fractality and nested EPI support
  4. Grammar Compliance - Operator sequences satisfy unified grammar U1-U6
  5. Structural Metrology - νf in Hz_str units, proper telemetry exposure
  6. Reproducible Dynamics - Deterministic evolution with seed control

Decision Framework

def should_implement(feature):
    """Decision framework for TNFR changes."""
    if weakens_tnfr_fidelity(feature):
        return False  # Reject, even if "cleaner"

    if not maps_to_operators(feature):
        return False  # Must map or be new operator

    if violates_invariants(feature):
        return False  # Hard constraint

    if not derivable_from_physics(feature):
        return False  # No organizational convenience ≠ physical necessity

    if not testable(feature):
        return False  # No untestable magic

    return True  # Implement with full documentation

Code Standards

Style Guidelines

Code Quality Tools

# Linting
ruff check src/

# Type checking
mypy src/tnfr/

# Formatting (if using black)
black src/ --line-length 100

Naming Conventions

Imports

# Standard library
from __future__ import annotations
import sys
from pathlib import Path
from typing import Optional, List, Dict

# Third-party
import networkx as nx
import numpy as np

# TNFR modules
from tnfr.operators.definitions import Emission, Coherence
from tnfr.metrics.coherence import compute_coherence
from tnfr.utils import get_logger

Module Organization (Phase 1 & 2)

The TNFR codebase is organized into focused modules for maintainability and cognitive load reduction:

Operators (tnfr.operators.*):

Grammar (tnfr.operators.grammar.*):

Metrics (tnfr.metrics.*):

Adding New Code:

Module Guidelines:

Testing Requirements

Test Coverage Goals

Required Test Types

  1. Unit tests - Test individual functions/classes
  2. Integration tests - Test operator sequences
  3. Property tests - Verify invariants hold (using Hypothesis)
  4. Example tests - Validate domain applications

Writing Tests

def test_coherence_monotonicity():
    """Coherence operator must not decrease C(t)."""
    G = nx.erdos_renyi_graph(20, 0.3)
    initialize_network(G)

    C_before = compute_coherence(G)
    apply_operator(G, node, Coherence())
    C_after = compute_coherence(G)

    assert C_after >= C_before, "Coherence must not decrease"

Test Naming

Running Tests

# Smoke tests (fast)
make smoke-tests

# Full suite
pytest

# Specific module
pytest tests/unit/operators/

# With coverage
pytest --cov=src/tnfr --cov-report=html

Documentation

Docstring Format

Use Google style docstrings:

def apply_operator(G: nx.Graph, node: int, operator: Operator) -> None:
    """Apply a structural operator to a network node.

    Args:
        G: NetworkX graph representing TNFR network
        node: Node identifier to apply operator to
        operator: Structural operator instance (AL, EN, IL, etc.)

    Raises:
        ValueError: If node not in graph
        GrammarViolation: If operator application violates grammar

    Examples:
        >>> G = nx.erdos_renyi_graph(10, 0.3)
        >>> apply_operator(G, 0, Emission())
        >>> apply_operator(G, 0, Coherence())
    """

Documentation Requirements

All contributions must include:

  1. Docstrings for all public functions/classes
  2. Type hints for function signatures
  3. Examples demonstrating usage
  4. Physics rationale linking to TNFR theory
  5. Tests covering documented behavior

Documentation Language Requirement

All project documentation MUST be written in English. This requirement is absolute and applies to:

Non-English text (including Spanish) is only permitted when:

In those cases the surrounding explanatory context MUST still be in English.

Rationale:

Enforcement:

Examples:

Compliant:

Added bifurcation benchmark sweeping OZ intensity and mutation thresholds.

Non-compliant:

Añadido benchmark de bifurcación con parámetros OZ.

If you need help translating, open a draft PR early and request assistance rather than merging mixed-language content.

By contributing you agree to maintain English as the sole canonical language for all project artifacts.

README Updates

If adding features, update:

Pull Request Process

Before Submitting

PR Template

## Description

[Clear description of what this PR does]

## Motivation

[Why is this change needed? What problem does it solve?]

## TNFR Alignment

- [ ] Preserves all 10 canonical invariants
- [ ] Maps to structural operators (specify which)
- [ ] Derivable from TNFR physics (reference TNFR.pdf or UNIFIED_UNIFIED_GRAMMAR_RULES.md)
- [ ] Maintains reproducibility (seeds, determinism)

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Examples demonstrate usage
- [ ] All tests pass locally

## Documentation

- [ ] Docstrings added/updated
- [ ] README updated (if needed)
- [ ] Examples added (if new feature)
- [ ] Physics rationale documented

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] No unintended files committed
- [ ] Branch name follows conventions
- [ ] Commit messages are descriptive

## Affected Components

[List modules/files modified]

## Breaking Changes

[List any breaking changes, or write "None"]

## Additional Notes

[Any other context, screenshots, or information]

Review Process

  1. Automated checks run (CI/CD)
  2. Maintainer review (typically 1-3 days)
  3. Feedback addressed by contributor
  4. Approval by maintainer
  5. Merge to main branch

After Merge

Theoretical Contributions

Adding New Operators

If proposing a new operator:

  1. Justify physically - Derive from nodal equation
  2. Define contracts - Pre/post-conditions
  3. Map to grammar - Which sets (generator, stabilizer, etc.)?
  4. Test rigorously - All invariants + specific contracts
  5. Document thoroughly - Physics → Math → Code chain

Template:

## Proposed Operator: [Name]

### Physical Basis
[How it emerges from TNFR physics]

### Nodal Equation Impact
∂EPI/∂t = ... [specific form]

### Contracts
- Pre: [conditions required]
- Post: [guaranteed effects]

### Grammar Classification
[Generator? Closure? Stabilizer? Destabilizer? etc.]

### Tests
- [List specific test requirements]

Extending Grammar

If proposing new grammar rules:

  1. Start from physics - Derive from nodal equation or invariants
  2. Prove canonicity - Show inevitability (Absolute/Strong)
  3. Document thoroughly - [Rule] → [Physics] → [Derivation] → [Canonicity]
  4. Test extensively - Valid/invalid sequence examples

Questions?

Final Principle

If a change "prettifies the code" but weakens TNFR fidelity, it is NOT accepted.
If a change strengthens structural coherence and paradigm traceability, GO AHEAD.

Reality is not made of things—it's made of resonance. Contribute accordingly.