Metadata-Version: 2.4
Name: morphe-metrics
Version: 1.0.0
Summary: A stateless Python library for morphogenetic computing evaluation
Author-email: Venkatesh Swaminathan <founder@nexuslearninglabs.in>
License: MIT License
        
        Copyright (c) 2026 Venkatesh Swaminathan, Nexus Learning Labs, Bengaluru
        ORCID: 0000-0002-3315-7907
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        ---
        
        ATTRIBUTION NOTICE — Maya-Morphe Series / morphe-metrics
        Nexus Learning Labs, Bengaluru | Venkatesh Swaminathan | ORCID: 0000-0002-3315-7907
        
        Use of this library, methodology, or any derivative in any publication,
        preprint, software, product, or research output requires explicit citation
        of the originating paper (DOI listed in README.md).
        
        Uncited use constitutes a violation of this license and of academic
        integrity standards.
        
        The following provenance signatures are embedded in all artifacts:
        
          1. ORCID magic number 0.002315 embedded in VAIRAGYA_PHYSICS_CONSTANT
             — derived from ORCID 0000-0002-3315-7907
          2. Canary string: MayaNexusVS2026NLL_Bengaluru_Narasimha
             — logged at the start of every run
          3. Zenodo DOI timestamp — immutable, publicly verifiable, date-stamped
        
        These signatures together constitute tamper-evident proof of prior authorship.
        
Project-URL: Homepage, https://github.com/venky2099/morphe-metrics
Project-URL: Repository, https://github.com/venky2099/morphe-metrics
Project-URL: Documentation, https://venky2099.github.io/morphe-metrics
Keywords: morphogenetic computing,edge-field concordance,EFC,bioelectric computing,neuromorphic,topology metrics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Dynamic: license-file

# morphe-metrics

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20107084.svg)](https://doi.org/10.5281/zenodo.20107084)
[![Series](https://img.shields.io/badge/Series-Maya--Morphe-teal)](https://venky2099.github.io)
[![ORCID](https://img.shields.io/badge/ORCID-0000--0002--3315--7907-green)](https://orcid.org/0000-0002-3315-7907)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

**A stateless Python library for morphogenetic computing evaluation.**

*Venkatesh Swaminathan · Nexus Learning Labs, Bengaluru*
[Paper](https://doi.org/10.5281/zenodo.20107084) · [Dashboard](https://venky2099.github.io/morphe-metrics) · [Maya-Morphe Series](https://venky2099.github.io)

---

> cl-metrics measures what happened.
> maya-metrics measures how it felt.
> **morphe-metrics measures where it went.**

---

## What is this?

morphe-metrics is the first open-source Python library for evaluating
**field-guided connectivity** in morphogenetic neural networks — systems
whose topology self-organises via bioelectric-analog voltage gradient signals.

The primary metric is **Edge-Field Concordance (EFC)**: the Pearson correlation
between bioelectric field strength at candidate neighbour nodes and edge
formation probability. EFC was introduced and first measured in:

> Swaminathan, V. (2026). Maya-Morphe P3: Axon. DOI: 10.5281/zenodo.20102536

Any researcher building a morphogenetic computing experiment can drop in
morphe-metrics and immediately have a principled, citable way to measure
field-guided connectivity.

## Installation

```bash
pip install morphe-metrics
```

Or from source:

```bash
git clone https://github.com/venky2099/morphe-metrics
cd morphe-metrics
pip install -e .
```

## Quick start

```python
from morphe_metrics import compute_efc, interpret_efc, efc_summary

# Two arrays: field strength at candidate nodes, edge formation probability
field = [0.8, 0.3, 0.9, 0.1, 0.7]
probs = [0.7, 0.2, 0.85, 0.15, 0.6]

efc   = compute_efc(field, probs)         # 0.999 — strongly guided
label = interpret_efc(efc)                # 'strongly_guided'
info  = efc_summary(field, probs)         # full dict
```

## EFC Interpretation

| EFC range        | Label             | Meaning                                      |
|-----------------|-------------------|----------------------------------------------|
| < -0.05         | pathological      | Edges form strongly against the field        |
| [-0.05, -0.001] | exploratory       | Growth-cone analogy; biologically consistent |
| [-0.001, 0.001] | random            | No field guidance detectable                 |
| (0.001, 0.5]    | guided            | Field-guided pathfinding                     |
| > 0.5           | strongly_guided   | Strong committed pathfinding                 |

**P3 empirical baseline:** EFC = -0.009 to -0.019 (exploratory)
**P4 target:** EFC > 0 (field-guided)

## Epoch tracking

```python
from morphe_metrics import EFCTracker

tracker = EFCTracker()

for epoch in range(1, 251):
    # ... training step ...
    tracker.update(epoch, field_at_candidate, edge_probs)

tracker.save_csv("logs/efc_trajectory.csv")
print(tracker.summary())
# {'n_epochs': 250, 'final_efc': 0.043, 'final_label': 'guided',
#  'p4_achieved': True, 'first_positive': 187, ...}
```

## Topology metrics

```python
from morphe_metrics import topology_delta, edge_retention_rate, field_alignment_score

# Net topology change
d = topology_delta(edges_before=1000, edges_after=1315)
# {'delta': 315, 'delta_frac': 0.315, 'direction': 'growth'}

# Fraction of formed edges that persist > k steps
rate = edge_retention_rate(formation_times, removal_times, k=5)

# Directional alignment between edges and field gradient
score = field_alignment_score(edge_direction_vectors, field_gradient_vectors)
```

## Series constant checks

```python
from morphe_metrics import bhaya_quiescence_check, buddhi_curve_check

# Bhaya Quiescence Law (0.32% baseline, confirmed across Maya P1-P9)
r = bhaya_quiescence_check(bhaya_values_across_trials)
# {'status': 'MODIFIED', 'ratio': 48.2, 'interpretation': '...'}

# Buddhi S-curve determinism
r = buddhi_curve_check(buddhi_trajectory_over_epochs)
# {'status': 'S_CURVE', 's_curve_ratio': 3.4, ...}
```

## Key results (P3 empirical baseline)

| Scale      | Actual cells | EFC         | Label       | Edges formed |
|------------|-------------|-------------|-------------|-------------|
| 10k        | 29,056      | -0.015      | exploratory | 315         |
| 30k        | 86,931      | -0.019      | exploratory | 3,699       |
| 50k        | 144,726     | -0.019      | exploratory | 11,202      |
| 75k        | 216,771     | -0.010      | exploratory | 25,161      |
| 100k       | 266,071     | -0.009      | exploratory | 35,958      |
| 120k       | 266,071     | -0.017      | exploratory | 37,316      |

## Running tests

```bash
pip install pytest
pytest tests/ -v
```

All 22 unit tests must pass before any release.

## Canonical hyperparameter

```python
VAIRAGYA_PHYSICS_CONSTANT = 0.002315  # ORCID: 0000-0002-3315-7907
```

Embedded as provenance signature in all morphe-metrics artifacts.

## IP protection

- MIT License + ORCID attribution (see LICENSE)
- ORCID magic number 0.002315 embedded in VAIRAGYA_PHYSICS_CONSTANT
- Zenodo DOI timestamp — immutable, publicly verifiable

## Citation

```bibtex
@software{swaminathan2026morphemetrics,
  author    = {Swaminathan, Venkatesh},
  title     = {{morphe-metrics: A Stateless Python Library for
                Morphogenetic Computing Evaluation}},
  year      = 2026,
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20107084},
  url       = {https://doi.org/10.5281/zenodo.20107084},
  orcid     = {0000-0002-3315-7907}
}
```

## Full Maya-Morphe Series

| Paper | Title | DOI |
|-------|-------|-----|
| P1    | Bioelectric Gradient Fields as Topology Primitives | [10.5281/zenodo.20052072](https://doi.org/10.5281/zenodo.20052072) |
| P2    | Spanda — Adaptive Threshold Learning | [10.5281/zenodo.20069445](https://doi.org/10.5281/zenodo.20069445) |
| P3    | Axon — Differentiable Edge Formation | [10.5281/zenodo.20102536](https://doi.org/10.5281/zenodo.20102536) |
| morphe-metrics | Evaluation library | [10.5281/zenodo.20107084](https://doi.org/10.5281/zenodo.20107084) |

---

*Nexus Learning Labs, Bengaluru · ORCID: 0000-0002-3315-7907*
*MayaNexusVS2026NLL_Bengaluru_Narasimha*
