Metadata-Version: 2.4
Name: openoptics-dcn
Version: 0.0.1
Summary: A research framework for designing, testing, and deploying optical datacenter networks
Author-email: Yiming Lei <ylei@mpi-inf.mpg.de>
License: # Software Copyright License for non-commercial scientific research purposes
        
        Please read carefully the following terms and conditions and any accompanying documentation before you download and/or use the Software OpenOptics, (the "Software"). By downloading and/or using the Software, you acknowledge that you have read these terms and conditions, understand them, and agree to be bound by them. If you do not agree with these terms and conditions, you must not download and/or use the Software. Any infringement of the terms of this agreement will automatically terminate your rights under this License.
        
        ## Ownership / Licensees
        
        The Software and the associated materials has been developed at the Max Planck Institute for Informatics (hereinafter "MPI") by the Network and Cloud Systems Group. (hereinafter "developers").
        
        Any copyright or patent right is owned by and proprietary material of the Max-Planck-Gesellschaft zur Förderung der Wissenschaften e.V. (hereinafter "MPG"; MPI and MPG hereinafter collectively "Max-Planck") hereinafter the "Licensor".
        
        ## License Grant
        
        Licensor grants you (Licensee) personally a single-user, non-exclusive, non-transferable, free of charge right:
        
        - To install the Software on computers owned, leased or otherwise controlled by you and/or your organization
        - To use the Software for the sole purpose of performing non-commercial scientific research, non-commercial education, or non-commercial artistic projects
        - To modify, adapt, translate or create derivative works based upon the software
        
        Any other use, in particular any use for commercial purposes, is prohibited. This includes, without limitation, incorporation in a commercial product, use in a commercial service, or production of other artefacts for commercial purposes. The Software may not be reproduced, modified and/or made available in any form to any third party without Max-Planck's prior written permission. Third party funded research at academic institution is considered non-Commercial Use. By downloading the Software, you agree not to reverse engineer it.
        
        This license also prohibits the use of the Software to train methods/algorithms/neural networks/etc. for commercial use of any kind.
        
        The Licensee is encouraged to / shall provide feedback on the use, results, modifications, bugs and technical questions or publications to ylei@mpi-inf.mpg.de.
        
        ## No Distribution
        
        The Software and the license herein granted shall not be copied, shared, distributed, re-sold, offered for re-sale, transferred or sub-licensed in whole or in part except that you may make one copy for archive purposes only and the use of the software by Other researchers at your institution under the conditions of this license.
        
        ## Disclaimer of Representations and Warranties
        
        You expressly acknowledge and agree that the Software results from basic research, is provided "AS IS", may contain errors, and that any use of the Software is at your sole risk. LICENSOR MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE SOFTWARE, NEITHER EXPRESS NOR IMPLIED, AND THE ABSENCE OF ANY LEGAL OR ACTUAL DEFECTS, WHETHER DISCOVERABLE OR NOT. Specifically, and not to limit the foregoing, licensor makes no representations or warranties (i) regarding the merchantability or fitness for a particular purpose of the Software, (ii) that the use of the Software will not infringe any patents, copyrights or other intellectual property rights of a third party, and (iii) that the use of the Software will not cause any damage of any kind to you or a third party.
        
        ## Limitation of Liability
        
        Because this Software License Agreement qualifies as a donation, according to Section 521 of the German Civil Code (Bürgerliches Gesetzbuch – BGB) Licensor as a donor is liable for intent and gross negligence only. If the Licensor fraudulently conceals a legal or material defect, they are obliged to compensate the Licensee for the resulting damage.
        
        Licensor shall be liable for loss of data only up to the amount of typical recovery costs which would have arisen had proper and regular data backup measures been taken. The foregoing applies also to Licensor's legal representatives or assistants in performance. Any further liability shall be excluded. Patent claims generated through the usage of the software cannot be directed towards the copyright holders.
        
        The software is provided in state of development the licensor defines. If modified or extended by Licensee, the Licensor makes no claims about the fitness of the software and is not responsible for any problems such modifications cause.
        
        ## No Maintenance Services
        
        You understand and agree that Licensor is under no obligation to provide either maintenance services, update services, notices of latent defects, or corrections of defects with regard to the Software. Licensor nevertheless reserves the right to update, modify, or discontinue the Software at any time.
        
        Defects of the software must be notified in writing to the Licensor with a comprehensible description of the error symptoms. The notification of the defect should enable the reproduction of the error. The Licensee is encouraged to communicate any use, results, modification or publication.
        
        ## Publications using the Software
        
        You acknowledge that the Software is a valuable scientific resource and agree to appropriately reference the following paper in any publication making use of the Software.
        
        Citation:
        ```
        @article{lei2024openoptics,
          title={OpenOptics: an open research framework for optical data center networks},
          author={Lei, Yiming and De Marchi, Federico and Li, Jialong and Joshi, Raj and Chandrasekaran, Balakrishnan and Xia, Yiting},
          journal={arXiv preprint arXiv:2411.18319},
          year={2024}
        }
        ```
        
        ## Commercial licensing opportunities
        
        For commercial uses of the Software, please send email to yxia@mpi-inf.mpg.de
        
        ## Miscellaneous
        
        This Agreement shall be governed by the laws of the Federal Republic of Germany except for the UN Sales Convention.
        
        This License Text is itself licensed under Creative Commons NC BY NA 4.0 https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en
Project-URL: Homepage, https://openoptics.mpi-inf.mpg.de
Project-URL: Documentation, https://openoptics.mpi-inf.mpg.de
Project-URL: Repository, https://github.com/mpi-ncs/openoptics
Project-URL: Paper, https://arxiv.org/abs/2411.18319
Keywords: networking,optical,datacenter,p4,mininet,tofino,ns-3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: System :: Networking
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: POSIX :: Linux
Classifier: License :: Other/Proprietary License
Classifier: License :: Free for non-commercial use
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.20
Requires-Dist: importlib_resources>=5.0; python_version < "3.9"
Provides-Extra: mininet
Requires-Dist: openoptics-dcn[dashboard]; extra == "mininet"
Requires-Dist: mininet>=2.3.0.dev6; extra == "mininet"
Requires-Dist: thrift>=0.22.0; extra == "mininet"
Provides-Extra: tofino
Requires-Dist: paramiko; extra == "tofino"
Requires-Dist: tomli; python_version < "3.11" and extra == "tofino"
Provides-Extra: ns3
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: dashboard
Requires-Dist: django<6,>=4.2; extra == "dashboard"
Requires-Dist: daphne; extra == "dashboard"
Requires-Dist: redis; extra == "dashboard"
Requires-Dist: channels; extra == "dashboard"
Requires-Dist: channels-redis; extra == "dashboard"
Requires-Dist: matplotlib>=3.5; extra == "dashboard"
Requires-Dist: Pillow; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: openoptics-dcn[dashboard,mininet,ns3,tofino]; extra == "all"
Dynamic: license-file

<div align="center">
<img alt="OpenOptics" src="https://raw.githubusercontent.com/mpi-ncs/openoptics/main/assets/openoptics_words.svg" width=20%>
<h3>
Easy design, testing, and deployment of optical datacenter networks for everyone
</h3>

<p>
| <a href="https://openoptics.mpi-inf.mpg.de/"><b>Documentation</b></a> | <a href="https://arxiv.org/abs/2411.18319"><b>Paper</b></a> |
</p>

</div>


---

*Latest News* 🔥

- [2026/03] [OpenOptics](https://ymlei.github.io/assets/OpenOptics_CR.pdf) has been accepted by NSDI'26!

---

# What is OpenOptics?

OpenOptics is a general framework for realizing different optical data center network architectures in a plug-and-play manner.
With OpenOptics, users can deploy customized optical data center networks on the testbed, emulation, or simulation with ~10 lines of python code.
Under the hood, user configurations are converted to control plane programs and deployed to the underlining OCSes and P4 switches.

Supported backends:
- **Mininet** — full software emulation using BMv2 software switches and Mininet networks.
- **Tofino** — deployment on Intel Tofino2 programmable switches (SDE 9.12.0). See [docs/tofino-backend.md](docs/tofino-backend.md).
- **ns-3** — packet-level simulation (scaffold; under active development).

# Quick Start

OpenOptics has two installation paths — pick the one that matches the backend
you need.

## For the Mininet backend: Docker image + `pip install`

The `ymlei/openoptics:latest` image ships a fully built BMv2, Mininet, Redis,
and all native dependencies. Add the Python package on top with pip.

```bash
# If you're on a remote machine, forward the dashboard port first:
ssh -L localhost:8001:localhost:8001 YOUR_MACHINE

# Pull and enter the container:
sudo docker pull ymlei/openoptics:latest
sudo docker run --privileged -dit --network host --name openoptics \
     ymlei/openoptics:latest /bin/bash
sudo docker exec -it openoptics bash

# Inside the container:
pip install "openoptics-dcn[mininet]"
openoptics-gen-examples          # copies ./examples/ into cwd
python3 examples/mininet_routing_direct_perhop.py
```

The dashboard (Redis + Django migrations + runserver) starts automatically when your script creates a `BaseNetwork` with `use_webserver=True` (the default).

Then try `h0 ping h1` / `h2 ping h3` inside the OpenOptics CLI.

VS Code Dev Containers also works — Ctrl+Shift+P → "Dev Containers: Reopen in
Container" after `git clone`ing this repo (`.devcontainer/` wires up the same
image).

If you'd rather build the image yourself or install editable from source,
see the [build-from-source section in `docs/installation.md`](docs/installation.md#advanced-build-from-source).

## For the Tofino backend: `pip install` (no Docker)

The Tofino backend only needs Python on your workstation — the heavy
dependencies (Intel SDE, P4 compiler) live on the switches and are invoked
over SSH.

```bash
pip install "openoptics-dcn[tofino]"
openoptics-gen-config            # writes ./openoptics-tofino.toml
# edit the placeholders (USER, jumphost.example.com, IPs, MACs), then run
# a Tofino example — see docs/tofino-backend.md for a full walkthrough.
```

See [docs/tofino-backend.md](docs/tofino-backend.md) for prerequisites and
config details.

## Bundled resources (all installs)

After `pip install`, these commands seed your working directory:

```bash
openoptics-gen-examples          # examples/
openoptics-gen-tutorials         # tutorials/
openoptics-gen-config            # openoptics-tofino.toml (Tofino config template)
```

# Usage

## With Example Scripts

```
python3 examples/mininet_routing_direct_perhop.py
```
Then you can try ping in your optical DCN,
```
h0 ping h1
h2 ping h3
```

## Defining Your Own Optical DCN with Python APIs

![OpenOptics Diagram](https://raw.githubusercontent.com/mpi-ncs/openoptics/main/assets/openoptics-diagram.png)

OpenOptics User APIs are located in `openoptics/Toolbox.py`.
This file defines a number of useful functions for creating optical topologies, deploying routing, and monitoring the network.
Every OpenOptics network is a `BaseNetwork` object:

```python
net = Toolbox.BaseNetwork(
    name="my_network",
    backend="Mininet",
    nb_node = 4,
    time_slice_duration_ms = 32, # in ms
    use_webserver=True)
```

You can use `connect(node1,port1,node2,port2,time_slice)` to connect ports of two nodes at the given time slice.
```python
net.connect(node1=0,port1=0,node2=1,port2=0,time_slice=0)
net.connect(node1=2,port1=0,node2=3,port2=0,time_slice=0)
net.connect(node1=0,port1=0,node2=2,port2=0,time_slice=1)
net.connect(node1=1,port1=0,node2=3,port2=0,time_slice=1)
net.deploy_topo()
```

Or you can use provided high-level topology generators:
```python
circuits = OpticalTopo.round_robin(nb_node=8)
net.deploy_topo(circuits)
```
or
```python
circuits = OpticalTopo.opera(nb_node = 8, nb_link=2)
net.deploy_topo(circuits)
```

Next, you can define routing by adding time-flow table entries (as forwarding tables in electrical DCNs) `add_time_flow_entry(node_id, entries, routing_mode)`.
Or use provided high-level routing generators:
```python
paths = OpticalRouting.routing_direct(net.get_topo())
net.deploy_routing(paths, routing_mode="Per-hop")
```

Once you have created a `BaseNetwork` object, and defined its topology and routing, start the network by simply calling `net.start()`.
Now run your Python file and your first optical DCN is deployed!

`net.start()` launches a command line interface defined in `src/OpticalCLI.py`.
This CLI is an extension of Mininet's CLI, with added support for optical DCNs, e.g. to query the number of queued packets in switches and the network's packet loss rate. 

You can find example scripts configuring different architectures under [examples/](examples/) — or, after `pip install`, run `openoptics-gen-examples` to copy them into your current directory.

## Monitor with OpenOptics Dashboard

![OpenOptics Dashboard](https://raw.githubusercontent.com/mpi-ncs/openoptics/main/assets/dashboard.png)

The dashboard starts automatically when you create a `BaseNetwork` with `use_webserver=True` (the default) — Redis is launched and Django migrations are applied in-process, so no separate setup step is needed.
In your web browser, visit http://0.0.0.0:8001 to view the dashboard.
The dashboard displays the network topology, along with realtime graphs of network performance served via WebSockets. 

Note: If you're running OpenOptics at a remote machine, make sure to enable port forwarding by passing `-L8001:0.0.0.0:8001` to ssh.

## Citation

If you use OpenOptics for your research, please cite our [paper](https://arxiv.org/abs/2411.18319):
```bibtex
@misc{lei2025openopticsopenresearchframework,
      title={OpenOptics: An Open Research Framework for Optical Data Center Networks}, 
      author={Yiming Lei and Federico De Marchi and Jialong Li and Raj Joshi and Balakrishnan Chandrasekaran and Yiting Xia},
      year={2025},
      eprint={2411.18319},
      archivePrefix={arXiv},
      primaryClass={cs.NI},
      url={https://arxiv.org/abs/2411.18319}, 
}
```

## Contact Us

<!-- --8<-- [start:contact-us] -->
- For technical questions and feature requests, please open a GitHub [Issues](https://github.com/mpi-ncs/openoptics/issues)
- For discussions and collaboration, contact us at [ylei@mpi-inf.mpg.de](mailto:ylei@mpi-inf.mpg.de)
<!-- --8<-- [end:contact-us] -->
