🧠 Revolutionary Cognitive Neural Networks: This package provides an easy and modular way to build and train neural networks using Torch, now enhanced with the groundbreaking P9ML Membrane Computing System for agentic cognitive grammar and adaptive neural-symbolic computation.

• 🚀 Quick Start
• 🏗️ Architecture Overview
• 🧠 P9ML Membrane Computing System
• 📦 Installation
• 🔧 Core Components
• 📚 Documentation
• 🧪 Examples
• ⚡ Performance
• 🛣️ Development Roadmap
• 🤝 Contributing

require('nn')

-- Traditional approach
local net = nn.Sequential()
net:add(nn.Linear(10, 8))
net:add(nn.ReLU())
net:add(nn.Linear(8, 2))

-- Revolutionary P9ML integration
local membrane1 = nn.P9MLMembrane(nn.Linear(10, 8), 'input_layer')
local membrane2 = nn.P9MLMembrane(nn.Linear(8, 2), 'output_layer')

-- Add cognitive capabilities
membrane1:addEvolutionRule(nn.P9MLEvolutionFactory.createGradientEvolution())
membrane2:enableQuantization(8, 0.1)

-- Create cognitive namespace
local namespace = nn.P9MLNamespace('cognitive_network')
namespace:registerMembrane(membrane1)
namespace:registerMembrane(membrane2)

-- Build cognitive grammar kernel
local kernel = nn.P9MLCognitiveKernel()
kernel:addLexeme({10, 8}, 'input_layer')
kernel:addLexeme({8, 2}, 'output_layer')

graph TB
    subgraph "P9ML Membrane Computing System"
        M[P9ML Membrane] --> NS[P9ML Namespace]
        M --> CK[Cognitive Kernel]
        M --> EV[Evolution Rules]
        
        NS --> HG[Hypergraph Topology]
        CK --> LEX[Lexemes]
        CK --> GR[Grammar Rules]
        EV --> QAT[Quantization Aware Training]
    end
    
    subgraph "Traditional Neural Network"
        L1[Linear Layer] --> R1[ReLU]
        R1 --> L2[Linear Layer]
        L2 --> S[Sigmoid]
    end
    
    M -.->|Wraps| L1
    M -.->|Wraps| L2
    
    subgraph "Cognitive Capabilities"
        META[Meta-Learning]
        FRAME[Frame Problem Resolution]
        GESTALT[Gestalt Fields]
    end
    
    CK --> META
    CK --> FRAME
    CK --> GESTALT

The P9ML Membrane Computing System transforms traditional neural networks into cognitive computing architectures with adaptive, self-modifying capabilities.

• Neural layers wrapped in computational membranes
• Cognitive evolution rules for adaptive behavior
• Quantization Aware Training (QAT) with data-free precision adaptation
• Quantum-inspired state management

• Global state coordination across membrane hierarchies
• Hypergraph topology for complex neural relationships
• Meta-learning orchestration for recursive adaptation
• Cognitive similarity mapping

• Tensor shapes as lexemes in cognitive vocabulary
• Membranes as grammar rules in production systems
• Prime factor tensor catalogs for mathematical representation
• Frame problem resolution through nested embeddings
• Gestalt tensor fields for unified cognitive representation

flowchart LR
    subgraph Input
        I[Input Tensor]
    end
    
    subgraph "P9ML Pipeline"
        I --> M1[Membrane 1]
        M1 --> E1[Evolution Rules]
        E1 --> Q1[Quantization]
        Q1 --> M2[Membrane 2]
        M2 --> E2[Evolution Rules]
        E2 --> Q2[Quantization]
    end
    
    subgraph "Cognitive Layer"
        Q2 --> NS[Namespace]
        NS --> CK[Cognitive Kernel]
        CK --> GF[Gestalt Field]
        GF --> FP[Frame Resolution]
    end
    
    subgraph Output
        FP --> O[Enhanced Output]
    end
    
    style M1 fill:#e1f5fe
    style M2 fill:#e1f5fe
    style CK fill:#f3e5f5
    style GF fill:#e8f5e8

• Torch 7
• LuaRocks package manager

luarocks install nn

git clone https://github.com/HyperCogWizard/nn9.git
cd nn9
luarocks make rocks/nn-scm-1.rockspec

th -lnn -e "print('nn loaded successfully')"

• Modules: The building blocks of neural networks

  • Module: Abstract class inherited by all modules
  • Containers: Composite and decorator classes like Sequential, Parallel, Concat
  • Transfer functions: Non-linear functions like Tanh and Sigmoid
  • Simple layers: Like Linear, Mean, Max
  • Convolution layers: Temporal, Spatial, Volumetric

• Criterions: Compute gradients according to loss functions

  • Criterions: Complete list including Criterion abstract class
  • MSECriterion: Mean Squared Error for regression
  • ClassNLLCriterion: Negative Log Likelihood for classification

graph TD
    subgraph "P9ML Core Components"
        PM[P9MLMembrane.lua<br/>• Wraps neural layers<br/>• Evolution rules<br/>• Quantization state]
        PN[P9MLNamespace.lua<br/>• Global coordination<br/>• Hypergraph topology<br/>• Meta-learning]
        PC[P9MLCognitiveKernel.lua<br/>• Lexeme management<br/>• Grammar rules<br/>• Frame resolution]
        PE[P9MLEvolution.lua<br/>• Adaptive rules<br/>• QAT algorithms<br/>• Success tracking]
    end
    
    subgraph "Support Components"  
        PV[P9MLVisualizer.lua<br/>• System diagrams<br/>• Topology maps<br/>• Debug views]
        PT[P9MLTest.lua<br/>• Unit tests<br/>• Integration tests<br/>• Benchmarks]
    end
    
    PM --> PN
    PM --> PC  
    PM --> PE
    PN --> PC
    PE --> PM
    
    PV -.-> PM
    PV -.-> PN
    PV -.-> PC
    PT -.-> PM
    PT -.-> PN
    PT -.-> PC
    PT -.-> PE
    
    style PM fill:#ffebee
    style PN fill:#e8f5e8
    style PC fill:#fff3e0
    style PE fill:#f3e5f5

• 📖 Overview: Package essentials including modules, containers and training
• 🎯 Training: How to train networks using StochasticGradient
• 🧪 Testing: How to test your modules
• 🏗️ Technical Architecture: Detailed P9ML system architecture

• 🧠 P9ML Integration Guide: Comprehensive P9ML usage examples
• 🔧 API Reference: Detailed API documentation
• 📊 Performance Benchmarks: Performance analysis and comparisons

• 🧬 Experimental Modules: Package containing experimental modules and criteria
• 🛣️ Development Roadmap: Strategic development plan with phases and actionable items

-- See examples/p9ml_example.lua for complete example
require('nn')

-- Create P9ML enhanced network
local net = nn.Sequential()
local membrane1 = nn.P9MLMembrane(nn.Linear(784, 128), 'input_processor')
local membrane2 = nn.P9MLMembrane(nn.Linear(128, 10), 'classifier')

-- Configure evolution rules
membrane1:addEvolutionRule(nn.P9MLEvolutionFactory.createGradientEvolution(0.01, 0.9))
membrane2:addEvolutionRule(nn.P9MLEvolutionFactory.createAdaptiveQuantization(8, 0.1))

-- Build network
net:add(membrane1):add(nn.ReLU()):add(membrane2):add(nn.LogSoftMax())

-- Create cognitive infrastructure
local namespace = nn.P9MLNamespace('mnist_classifier')
namespace:registerMembrane(membrane1, 'feature_extractor')
namespace:registerMembrane(membrane2, 'decision_layer')

local kernel = nn.P9MLCognitiveKernel()
kernel:addLexeme({784, 128}, 'feature_transformation')
kernel:addLexeme({128, 10}, 'classification_transformation')

• Computer Vision: Spatial membrane computing for image processing
• Natural Language: Temporal membranes for sequence modeling
• Reinforcement Learning: Adaptive membranes for policy optimization
• Meta-Learning: Recursive namespace orchestration for few-shot learning

• Adaptive Quantization: Reduces memory usage while maintaining accuracy
• Evolution Rules: Optimize computation paths during training
• Cognitive Caching: Reuse computed gestalt fields for efficiency
• Parallel Namespace: Distributed computation across membrane hierarchies

The HyperCogWizard nn9 project follows a structured development plan to advance P9ML membrane computing capabilities:

• Complete Development Roadmap: 18-month strategic plan with 6 phases
• Quick Reference: Current priorities and next quarter goals
• Milestones Tracking: Progress tracking and metrics dashboard
• Phase 1 Action Items: Detailed sprint planning for current phase

• Objective: Stabilize P9ML foundation with comprehensive testing
• Key Goals: 95% test coverage, performance baselines, API standardization
• Next Milestone: Complete migration tutorial and 10+ working examples

1. Phase 2 (Months 3-5): Core P9ML Enhancement - Advanced evolution rules and cognitive kernels
2. Phase 3 (Months 6-8): Advanced Cognitive Features - Gestalt fields and meta-learning
3. Phase 4 (Months 9-11): Performance & Scalability - Production optimization
4. Phase 5 (Months 12-14): Ecosystem Integration - Framework bridges and tools
5. Phase 6 (Months 15-18): Research & Innovation - Neuromorphic and quantum computing

We welcome contributions to both the core neural network package and the P9ML system!

git clone https://github.com/HyperCogWizard/nn9.git
cd nn9
luarocks make rocks/nn-scm-1.rockspec

# Run all tests
th test.lua

# Run P9ML specific tests  
th -lnn -e "require('nn.P9MLTest').runAllTests()"

# Run specific component tests
th -lnn -e "nn.test{'P9MLMembrane'}"

• Follow Lua conventions and existing codebase patterns
• Add comprehensive tests for new features
• Update documentation for API changes
• Use descriptive variable names and comments

• Core NN Components: Traditional neural network layers and criterions
• P9ML System: Membrane computing and cognitive capabilities
• Documentation: Examples, tutorials, and API references
• Performance: Optimization and benchmarking
• Testing: Unit tests and integration tests

This project is licensed under the BSD 3-Clause License - see the COPYRIGHT.txt file for details.

• Torch Team: For the foundational neural network framework
• P9ML Researchers: For advancing membrane computing theory
• Community Contributors: For ongoing development and testing