Metadata-Version: 2.4
Name: opennandlab
Version: 2.0.0
Summary: Open-Source SSD Controller & 3D NAND Research Platform
Author-email: Mudit Bhargava <muditbhargava666@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Mudit Bhargava
        
        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.
        
Project-URL: Homepage, https://github.com/muditbhargava66/OpenNANDLab
Project-URL: Bug Tracker, https://github.com/muditbhargava66/OpenNANDLab/issues
Project-URL: Documentation, https://github.com/muditbhargava66/OpenNANDLab
Project-URL: Source Code, https://github.com/muditbhargava66/OpenNANDLab
Keywords: 3D NAND,NAND flash,flash storage,SSD,simulator,FTL,wear leveling,error correction,ECC,LDPC,BCH
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: lz4>=4.3.2
Requires-Dist: zstd>=1.5.5.0
Requires-Dist: jsonschema>=4.17.3
Requires-Dist: click>=8.0.0
Requires-Dist: streamlit>=1.28.0
Requires-Dist: plotly>=5.18.0
Requires-Dist: methodtools>=0.4.7
Provides-Extra: dev
Requires-Dist: tox>=4.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.4.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: hypothesis>=6.98.0; extra == "dev"
Requires-Dist: uv>=0.1.0; extra == "dev"
Dynamic: license-file

<div align="center">

# OpenNANDLab

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org/)
[![CI](https://github.com/muditbhargava66/OpenNANDLab/actions/workflows/ci.yml/badge.svg)](https://github.com/muditbhargava66/OpenNANDLab/actions/workflows/ci.yml)
[![Code Quality](https://img.shields.io/badge/code%20quality-A-brightgreen.svg)](https://github.com/muditbhargava66/OpenNANDLab)
[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://github.com/muditbhargava66/OpenNANDLab/docs)
[![Documentation](https://img.shields.io/badge/docs-readthedocs.io-blue)](https://OpenNANDLab.readthedocs.io/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)

**Open-Source SSD Controller & 3D NAND Research Platform**

> A comprehensive toolkit for optimizing 3D NAND flash storage performance, reliability, and efficiency through advanced defect handling, performance optimization, firmware integration, and NAND characterization.

</div>

---

## 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

```bash
# 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:

```bash
# 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:

```bash
opennandlab dashboard
```

### API Usage

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

```python
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:

```yaml
# 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](docs/ARCHITECTURE.md).

## Directory Structure

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

```text
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:
```bash
cd docs
pip install -r requirements.txt
sphinx-build -b html . _build/html
```

Read more about specific modules:
- [User Manual](docs/USER_MANUAL.md) - Installation, configuration, and usage guide
- [API Reference](docs/API_REFERENCE.md) - Detailed API documentation
- [Data Flow](docs/DATA_FLOW.md) - 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](examples/basic_operations.py) - Reading, writing, and erasing
- [Error Correction](examples/error_correction.py) - Using BCH and LDPC coding
- [Data Compression](examples/compression.py) - LZ4 and Zstandard compression
- [Caching](examples/caching.py) - Using different eviction policies
- [Wear Leveling](examples/wear_leveling.py) - Advanced wear leveling techniques
- [Firmware Generation](examples/firmware_generation.py) - 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](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. 

```bash
# 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

| Python Version | Linux | macOS | Windows |
|----------------|-------|-------|---------|
| 3.10           | Pass  | Pass  | Pass    |
| 3.11           | Pass  | Pass  | Pass    |
| 3.12           | Pass  | Pass  | Pass    |

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<div align="center">
  
**If you find OpenNANDLab useful, please consider giving it a star on GitHub!**
  
**Contact**: [@muditbhargava66](https://github.com/muditbhargava66)  
**Report Issues**: [Issue Tracker](https://github.com/muditbhargava66/OpenNANDLab/issues)
  
© 2026 Mudit Bhargava. [MIT License](LICENSE)  
</div>
