Metadata-Version: 2.4
Name: mnt.nanoplacer
Version: 0.3.0
Summary: NanoPlaceR - An open-source framework for placement and routing of Field-coupled Nanotechnologies based on reinforcement learning.
Author-email: Simon Hofmann <simon.t.hofmann@tum.de>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cda-tum/NanoPlaceR
Project-URL: Bug Tracker, https://github.com/cda-tum/NanoPlaceR/issues
Project-URL: Discussions, https://github.com/cda-tum/NanoPlaceR/discussions
Project-URL: Research, https://www.cda.cit.tum.de/research/fcn/
Keywords: FCN,physical design
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gymnasium>=0.29.1
Requires-Dist: mnt.pyfiction>=0.8.0
Requires-Dist: networkx>=3.2.1
Requires-Dist: numpy>=1.26.3
Requires-Dist: sb3-contrib>=2.8.0
Requires-Dist: tensorboard>=2.15.1
Provides-Extra: test
Requires-Dist: pytest>=8.2.1; extra == "test"
Provides-Extra: coverage
Requires-Dist: mnt.nanoplacer[test]; extra == "coverage"
Requires-Dist: pytest-cov; extra == "coverage"
Provides-Extra: gui
Requires-Dist: flask>=3.1; extra == "gui"
Dynamic: license-file

[![PyPI](https://img.shields.io/pypi/v/mnt.nanoplacer?logo=pypi&style=flat-square)](https://pypi.org/project/mnt.nanoplacer/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/github/actions/workflow/status/cda-tum/mnt-nanoplacer/deploy.yml?branch=main&style=flat-square&logo=github&label=python)](https://github.com/cda-tum/mnt-nanoplacer/actions/workflows/deploy.yml)
[![Ruff](https://img.shields.io/badge/lint%20%26%20format-Ruff-D7FF64?style=flat-square&logo=ruff)](https://docs.astral.sh/ruff/)

# NanoPlaceR: Reinforcement-learning placement and routing for FCN

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cda-tum/mnt-nanoplacer/main/docs/_static/mnt_light.svg" width="60%">
    <img src="https://raw.githubusercontent.com/cda-tum/mnt-nanoplacer/main/docs/_static/mnt_dark.svg" width="60%" alt="Munich Nanotech Toolkit logo">
  </picture>
</p>

NanoPlaceR is an open-source physical-design tool for field-coupled nanocomputing (FCN). It uses masked Proximal Policy Optimization to place logic elements and routes each partial placement with A\* search. It can generate layouts for logic networks of roughly 200 gates while using about 50% less area than the state-of-the-art heuristic approach described in the publications below.

![Overview of the NanoPlaceR methodology](https://raw.githubusercontent.com/cda-tum/mnt-nanoplacer/main/docs/_static/lbr.png)

## Installation

NanoPlaceR supports Python 3.11 through 3.14 and requires `mnt.pyfiction` 0.8 or newer. The CI suite covers both ends of that range.

```console
python -m venv .venv
source .venv/bin/activate
python -m pip install mnt.nanoplacer
```

On Windows, activate the environment with `.venv\Scripts\activate`.

## Usage

Use NanoPlaceR from Python:

```python
from mnt.nanoplacer import create_layout

create_layout(
    benchmark="trindade16",
    function="mux21",
    clocking_scheme="2DDWave",
    technology="QCA",
    minimal_layout_dimension=False,
    layout_width=3,
    layout_height=4,
    time_steps=10_000,
    reset_model=True,
    verbose=1,
    optimize=True,
)
```

Or use the command-line interface:

```console
mnt.nanoplacer --help
mnt.nanoplacer --benchmark trindade16 --function mux21 \
  --clocking-scheme 2DDWave --technology Gate-level \
  --minimal-layout-dimension --time-steps 10000 --verbose 1
```

Runs store generated layouts in `layouts/`, trained agents in `models/`, and TensorBoard data in `tensorboard/`. By default, the CLI resumes a matching saved model when one exists; pass `--reset-model` to train from scratch.

## Browser interface

Install the optional standalone GUI and launch it locally:

```console
python -m pip install "mnt.nanoplacer[gui]"
mnt.nanoplacer.gui
```

The interface opens at `http://127.0.0.1:5056`. Use `--port 5057` to choose another port, `--no-browser` to suppress automatic opening, or `--runs-dir PATH` to choose where experiments are saved.

Choose a bundled circuit, technology and clocking scheme, then configure its grid, random seed and training budget. The canvas shows the best partial placement, including the actual clock phases; completed solutions are identified separately. SiDB uses 2DDWave during training and converts its output to a hexagonal layout. Optimization is available for 2DDWave only. Predefined minimum dimensions are experimental targets, not a guarantee that every seed or budget will find a solution.

Training runs in a separate process, one run at a time per GUI instance. Reloading the page restores its current progress. The training statistics panel plots the mean return of the latest 100 completed episodes (fewer at the start), with sampled history and timesteps relative to the current run. It shows the agent's training reward, not an independent layout-quality score. Cancel requests a graceful stop and checkpoint save; if a native operation prevents that, the worker is terminated after a short grace period. Earlier run folders are preserved. A finished training budget without a solution is reported honestly as such. PPO may finish its current rollout beyond the requested timestep budget.

Each run has its own folder under `nanoplacer-runs/`, with configuration, log, previews, generated layouts and a saved agent. Downloads become available when the worker stops writing its outputs. The resume option copies the latest compatible agent into a new run; circuit, technology, clocking scheme and grid size must match. Only checkpoints in local run folders are accepted; never add untrusted model files to them. Gate-level FGL output is also kept for complete solutions alongside the selected technology's usual output. Downloaded layouts can be opened in other MNT tools where their topology and clocking scheme are supported.

This is a **local workstation interface**, bound to loopback, not a multi-user hosted service. It supports bundled benchmarks, grids up to 128 × 128, and budgets up to 10 million timesteps. The Python API and original CLI remain available without the GUI dependency.

## Repository structure

```text
src/mnt/nanoplacer/
├── benchmarks/                  Verilog benchmark circuits
├── main.py                      Python and command-line entry point
└── placement_envs/
    ├── nano_placement_env.py    Gymnasium placement environment
    └── utils/
        ├── layout_dimensions.py Predefined minimal dimensions
        └── placement_utils.py   Network and action helpers
tests/                           Unit and integration tests
```

## References

If you use NanoPlaceR in your work, please cite the following publications:

- [Late Breaking Results From Hybrid Design Automation for Field-coupled Nanotechnologies (DAC 2023)](https://www.cda.cit.tum.de/files/eda/2023_dac_late_breaking_results_from_hybrid_design_automation_for_field_coupled_nanotechnologies.pdf)
- [Thinking Outside the Clock: Physical Design for Field-coupled Nanocomputing with Deep Reinforcement Learning (ISQED 2024)](https://www.cda.cit.tum.de/files/eda/2024_isqed_thinking_outside_the_clock_physical_design_for_field-coupled_nanocomputing_with_deep_reinforcement_learning.pdf)

```bibtex
@INPROCEEDINGS{hofmann2023nanoplacer,
  author        = {S. Hofmann and M. Walter and L. Servadei and R. Wille},
  title         = {{Late Breaking Results From Hybrid Design Automation for Field-coupled Nanotechnologies}},
  booktitle     = {{2023 60th ACM/IEEE Design Automation Conference (DAC)}},
  year          = {2023},
}
```

```bibtex
@INPROCEEDINGS{hofmann2024nanoplacer,
  author        = {S. Hofmann and M. Walter and L. Servadei and R. Wille},
  title         = {{Thinking Outside the Clock: Physical Design for Field-coupled Nanocomputing with Deep Reinforcement Learning}},
  booktitle     = {{2024 25th International Symposium on Quality Electronic Design (ISQED)}},
  year          = {2024},
}
```
