Contributions should make an implemented behavior, mathematical statement or documented limitation more accurate and useful. The nodal equation does not make every configured algorithm a derived physical law. Read the contributor and agent instructions before changing the repository. The research program owns the objective, current question and technical chapters; the instructions explain how to preserve their scope.
Use a separate environment and an editable checkout. Supported interpreters and
dependency groups are defined in pyproject.toml.
TESTING.md owns installation and validation
commands; the workflow guide describes CI and links its
authoritative workflow YAML. There are
no dev or all extras: choose a defined group for the work at hand.
Before editing, inspect the affected source, tests and specialized documentation. Search for an existing owner of the calculation or contract. Preserve unrelated working-tree changes and keep a contribution focused enough to review.
- State the problem and intended behavior. For a suspected defect, record a reproducer or counterexample when practical.
- Reuse existing numerical kernels, readers, validation and telemetry. Add an abstraction when it removes real duplication or establishes a useful boundary.
- Implement the change and run checks appropriate to its scope, following TESTING.md.
- Update the document that owns the affected definition or interface. Link to that owner instead of copying its derivation or inventory.
- Describe the result, validation and remaining limitations in the pull request.
The theory catalog locates definitions and their assumptions. API contracts and operator contracts specify execution.
- Distinguish initial state construction, named operator maps and continuous nodal integration: their contracts differ.
- Declare state representation, pressure law, phase/capacity/support inputs, numerical domain and any held parameters.
- Separate exact identities, conditional theorems, finite runtime observations and hypotheses. Tests provide evidence within their asserted domain.
- Treat grammar admission and diagnostic thresholds as implemented contracts. Neither a high score nor an accepted sequence proves global stability or empirical validity.
- Reuse named configuration values and document their units and provenance. A configured coefficient is not automatically a uniquely derived constant.
pyproject.toml configures Black and isort at 88 columns, flake8 and NumPy-style docstrings. Use explicit imports, meaningful names and type annotations consistent with the surrounding API. Update maintained public stubs when an exposed signature changes; do not generate unrelated stubs.
Tool commands live in TESTING.md. Current CI distinguishes blocking checks from advisory analysis; a contributor checklist must not silently impose a different policy.
Use the testing guide. Meaningful tests check observable behavior or a mathematical contract, with independent expected results where possible. A regression should cover the failure it prevents. Small documentation changes do not require numerical tests. The project does not configure a universal coverage percentage or require every change to increase coherence.
Performance comparisons need a reproducible workload, environment, cache state and measurement protocol. An optimization that changes the result needs an explicit accuracy or behavior tradeoff.
Keep technical code, comments, documentation, commits and pull requests in English. Verbatim quotations and raw data retain their original language.
Use the research program for the sole active question, scientific priorities and technical studies. The theory index is its generated chapter catalog; the documentation index routes usage material. The old plan, strategy and portfolio are retired compatibility routes.
Open theory/RESEARCH_PROGRAM.md for the research objective and current task.
Follow its links or the generated theory catalog to open and edit each canonical
chapter directly in VS Code. Each chapter is an ordinary Markdown file; preview
loads that chapter alone. The metadata-only theory/research_catalog.json
declares ordering, titles and retired routes without duplicating chapter prose.
The chapter reader also supports optional working-copy extraction:
python scripts/research_book.py list
python scripts/research_book.py extract theory/NODAL_PARAMETER_FOUNDATIONS.md --file chapter-working.md
# Edit chapter-working.md, then replace only that chapter:
python scripts/research_book.py replace theory/NODAL_PARAMETER_FOUNDATIONS.md --file chapter-working.mdExtraction requires a new output file. Replacement writes the canonical chapter while preserving other sources and its published route. Direct chapter edits are visible to all documentation tools. Keep the research program within 96 KiB and each chapter, program and maintained guide within 4,000 physical lines. Do not concatenate the corpus into a maintained Markdown preview. Regenerate checked views after changing their inputs and run the documentation checks.
Explain current behavior in maintained guides and contracts; keep results with their proof/evidence chapters and avoid delivery logs in overviews. Preserve valid anchors and immutable evidence. Check imports, public consumers and frozen dependencies before retiring obsolete material. Record its Git revision/blob and replacement instead of keeping superseded instructions or known errors as active guidance. Preserve unique proofs, counterexamples and frozen source records. Do not create a competing task list or catalog.
Use the pull request template. Lead with the problem and resulting behavior, then provide commands actually run, relevant results and untested scope. Identify changes to public APIs, serialization, dependencies or model assumptions. Link evidence instead of pasting duplicate reports. This guide promises no review or release deadline.
Publication triggers and conditions are documented in the workflow guide and implemented in its linked YAML; a merge alone does not imply a new release.
State definitions and independent assumptions before the derivation. Include countercontrols and failure domains. A proposed operator, grammar rule or constitutive law needs its own mathematical and implementation contract; the nodal identity alone establishes neither uniqueness nor necessity. For an application, distinguish an observation map from a tested prediction and keep calibration separate from evaluation. Negative results can narrow a hypothesis.
Use the domain-extension form to propose an application. Describe its inputs, patterns, existing APIs, intended outputs, evaluation, limitations and maintenance. Visualizations or recipes can be included when useful; no nonexistent base class, fixed directory skeleton or universal diagnostic-score threshold is required.
Discuss ideas and evidence respectfully. Avoid harassment, personal attacks and publication of private information. Report ordinary bugs and proposals through repository issues. For vulnerabilities, follow SECURITY.md instead of posting exploit details publicly.