Features

OpenNANDLab brings a unified, modern architecture designed for hardware researchers and storage engineers:

• NAND Defect Handling

  • Advanced BCH and LDPC error correction implementations (including Forney's algorithm and belief propagation).
  • Dynamic bad block management and factory defect tracking.
  • Intelligent wear leveling algorithms utilizing Min-Heap prioritization for optimal block rotation.

• Performance Optimization

  • Adaptive data compression (LZ4/Zstandard) directly integrated into the logical-to-physical (L2P) pipeline.
  • Multi-policy caching system (LRU, LFU, FIFO, TTL) replacing naive lookup buffers.
  • Parallel access operations designed to simulate multi-plane NAND concurrency.

• Flash Translation Layer (FTL)

  • Page-level flat-array L2P mapping for extreme memory efficiency.
  • Robust Garbage Collection (GC) utilizing Greedy and Cost-Benefit algorithms.
  • Asynchronous Write Buffering logic mapped accurately to physical block boundaries.

• Firmware Integration

  • Template-based firmware specification generation directly mapped via Pydantic.
  • Comprehensive validation with schema and semantic rules.
  • Automated test bench execution for custom workloads.

• NAND Characterization & Analytics

  • Real-time data collection and statistical analysis.
  • Dynamic derivation of the Write Amplification Factor (WAF), IOPS, and Error Rates.
  • Visualization of wear patterns and error distributions.

• User Interfaces

  • Streamlit dashboard for interactive visual tracking.
  • Unified command-line interface (CLI) powered by Click.
  • Python API for deep-integration with external pipelines.

Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package installer)

From Source

# Clone the repository
git clone https://github.com/muditbhargava66/OpenNANDLab.git

# Navigate to the project directory
cd OpenNANDLab

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate.bat

# Install dependencies in development mode
pip install -e ".[dev]"

Quick Start

Using the Command Line Interface (CLI)

OpenNANDLab provides a powerful unified CLI. Use it for script-based or terminal operations:

# Run a basic simulation using a random write workload
opennandlab run --workload random_write

# Run performance benchmarks using specific configurations
opennandlab benchmark --config specs/firmware_spec_standard_tlc_nand.yaml

# Characterize current device wear and errors
opennandlab characterize --samples 100 --output-dir results/

Dashboard

Launch the Streamlit dashboard for interactive operation and visualization of your storage characteristics:

opennandlab dashboard

API Usage

If you prefer script-level integration, you can directly import the NANDController and SimulatorConfig from the opennandlab namespace:

from opennandlab.simulator import NANDController
from opennandlab.config import SimulatorConfig

# Load standard configuration defaults
config = SimulatorConfig()

# Create controller and initialize
controller = NANDController(config, simulation_mode=True)
controller.initialize()

# Perform basic operations using Logical Block Numbers (LBN)
controller.write_page(0, b'Hello, NAND world!')
data = controller.read_page(0)
print(data)  # b'Hello, NAND world!'

# Clean up
controller.shutdown()

Configuration

The simulator is securely driven by Pydantic configuration models (SimulatorConfig), replacing outdated dictionaries. It natively validates nested attributes to ensure hardware simulation safety.

Default Configuration Example

Configurations are provided in standard YAML formatting. A typical template might look like:

# NAND Flash Physical Configuration
nand:
  cell_type: "TLC"
  page_size_bytes: 4096
  pages_per_block: 256
  blocks_per_plane: 1024
  oob_size_bytes: 128
  max_pe_cycles: 3000

# Flash Translation Layer Configuration
ftl:
  type: "page"
  gc_policy: "greedy"
  gc_trigger_free_pct: 0.10
  over_provisioning_pct: 0.07
  write_buffer_pages: 64

# Optimization Configuration
ecc:
  algorithm: "bch" 
  bch_m: 8          
  bch_t: 4          

You can point to these templates using the CLI (--config) or programmatically load them via load_config('path.yaml').

Architecture

OpenNANDLab's architecture enforces strict separation of concerns, decoupling logical translation (FTL) from hardware execution (NAND Device) while intercepting reads/writes for telemetry.

For full details, please read our Architecture Document.

Directory Structure

The project has been aggressively restructured in v2.0.0 for maintainability and scalability:

OpenNANDLab/
├── docs/                      # ReadTheDocs Markdown & Asset Storage
│   ├── resources/             # Configuration templates and images
│   ├── API_REFERENCE.md       # Full Python API breakdown
│   ├── ARCHITECTURE.md        # Central design document
│   ├── BENCHMARKS.md          # Expected performance references
│   ├── CONTRIBUTING.md        # Open Source contribution guidelines
│   ├── DATA_FLOW.md           # Pipeline execution maps
│   ├── EXAMPLES.md            # Guide to example implementations
│   ├── FIRMWARE_INTEGRATION.md
│   ├── FTL_DESIGN.md          # Flash Translation Layer structures
│   ├── INDEX.md               # Main Sphinx documentation index
│   ├── NAND_CHARACTERIZATION.md
│   ├── NAND_DEFECT_HANDLING.md
│   ├── PERFORMANCE_OPTIMIZATION.md
│   ├── REFERENCES.md          # Academic paper citations
│   ├── SCRIPTS_AND_SPECS.md   # Setup rules
│   └── USER_MANUAL.md         # General end-user handbook
├── examples/                  # Python examples showing programmatic usage
├── specs/                     # YAML files detailing hardware templates
├── src/
│   └── opennandlab/           # Main Python Package
│       ├── analytics/         # Data collection & WAF metrics
│       ├── defect/            # Bad block management & Wear leveling
│       ├── ecc/               # LDPC & BCH logic
│       ├── firmware/          # Spec generators
│       ├── ftl/               # Logical-to-Physical translation and GC
│       ├── nand/              # Raw hardware simulators
│       ├── optimization/      # Caching & Compression algorithms
│       ├── utils/             # Loggers & file handlers
│       ├── visualization/     # Streamlit interfaces
│       ├── workloads/         # Synthesized data flows
│       ├── cli.py             # Click command-line entrypoint
│       ├── config.py          # Pydantic configuration schemas
│       └── simulator.py       # Main NANDController orchestrator
├── tests/                     # Pytest suite (Unit, Integration, Property)
├── tox.ini                    # Tox configuration for multi-version testing
├── pyproject.toml             # Python build and dependencies list
├── CHANGELOG.md               # Versioning history
├── CODE_OF_CONDUCT.md         # Contributor conduct guidelines
└── SECURITY.md                # Vulnerability handling

Documentation

Comprehensive, web-ready documentation is available. You can build it locally or view it online via ReadTheDocs.

To generate the documentation locally:

cd docs
pip install -r requirements.txt
sphinx-build -b html . _build/html

Read more about specific modules:

• User Manual - Installation, configuration, and usage guide
• API Reference - Detailed API documentation
• Data Flow - Execution mappings

Examples

The examples directory contains standalone python scripts demonstrating various features of OpenNANDLab. You can run these directly to see the console output of internal subsystems:

• Basic Operations - Reading, writing, and erasing
• Error Correction - Using BCH and LDPC coding
• Data Compression - LZ4 and Zstandard compression
• Caching - Using different eviction policies
• Wear Leveling - Advanced wear leveling techniques
• Firmware Generation - Creating firmware specs

Contributing

OpenNANDLab welcomes external contributors! If you're looking to help improve the project:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for more information on commit conventions and architectural decision making.

Development and Testing

The project uses pytest for internal validation, ruff for code styling, and tox for multi-environment execution.

# Setup pre-commit hooks
pre-commit install

# Run type checking
tox -e type

# Run code linting
tox -e lint

# Run all unit and integration tests locally
pytest

# Run tests with a detailed coverage report
pytest --cov=src/opennandlab tests/

We rigorously enforce code quality. All new pull requests must maintain at least 80% test coverage and zero linting errors.

Compatibility Matrix

License

This project is licensed under the MIT License - see the LICENSE file for details.