### Running an Example with Dockerized OpenLane

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/migrants/index.md

This example demonstrates how to clone the OpenLane repository, set up the PDK, mount the environment, and run a design using the Dockerized OpenLane installation. It shows the command-line interface for starting the OpenLane environment from any location.

```bash
git clone https://github.com/The-OpenROAD-Project/OpenLane
make pdk
make mount
./flow.tcl -design spm
```

```bash
pip3 install --upgrade openlane
openlane --dockerized --run-example spm
```

--------------------------------

### Example Setup Timing Report

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/timing_closure/index.md

This snippet shows an example of a worst negative slack report for setup timing, indicating the maximum deviation from the required timing constraints.

```text
===========================================================================
Worst Negative Slack (Setup)
============================================================================
nom_tt_025C_1v80: 0.0

```

--------------------------------

### Run SPM Example with OpenLane2

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/nix_installation/_running_example.md

Create a directory for your designs, navigate into it, and run the 'spm' example using OpenLane2. This is a basic test to ensure the installation is working correctly.

```bash
mkdir my_designs
cd my_designs/
openlane --run-example spm
```

--------------------------------

### Setup Nix Package Manager

Source: https://github.com/chipfoundry/openlane2/blob/main/notebook.ipynb

Installs the Nix package manager and enables the experimental 'flakes' feature. This is the primary method for installing OpenLane 2. If not in Colab, ensure Nix is installed and flakes are enabled manually.

```python
# @title Setup Nix {display-mode: "form"}
# @markdown <img src="https://raw.githubusercontent.com/NixOS/nixos-artwork/master/logo/nix-snowflake.svg" width="32"/>
# @markdown
# @markdown Nix is a package manager with an emphasis on reproducible builds,
# @markdown and it is the primary method for installing OpenLane 2.
# @markdown
# @markdown This step installs the Nix package manager and enables the
# @markdown experimental "flakes" feature.
# @markdown
# @markdown If you're not in a Colab, this just sets the environment variables.
# @markdown You will need to install Nix and enable flakes on your own following
# @markdown [this guide](https://openlane2.readthedocs.io/en/stable/getting_started/common/nix_installation/index.html).
import os
import sys
import shutil

os.environ["LOCALE_ARCHIVE"] = "/usr/lib/locale/locale-archive"

if "google.colab" in sys.modules:
    if shutil.which("nix-env") is None:
        !curl -L https://nixos.org/nix/install | bash -s -- --daemon --yes
        !echo "extra-experimental-features = nix-command flakes" >> /etc/nix/nix.conf
        !killall nix-daemon
else:
    if shutil.which("nix-env") is None:
        raise RuntimeError("Nix is not installed!")

os.environ["PATH"] = f"/nix/var/nix/profiles/default/bin/:{os.getenv('PATH')}"

```

--------------------------------

### Run OpenLane Example

Source: https://github.com/chipfoundry/openlane2/blob/main/Readme.md

An example command to run OpenLane with a specific PDK root and configuration file.

```sh
python3 -m openlane --pdk-root $HOME/.volare ./designs/spm/config.json
```

--------------------------------

### Install PDK with OpenLane 1

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/migrants/index.md

Use 'make pdk' to install PDKs in OpenLane 1. OpenLane 2 automates this using Volare.

```bash
make pdk
```

--------------------------------

### Minimal YAML Configuration Example

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/reference/configuration.md

A basic YAML configuration file demonstrating essential design parameters and PDK-specific settings, equivalent to the JSON example.

```yaml
DESIGN_NAME: spm
VERILOG_FILES: dir::src/*.v
CLOCK_PORT: clk
CLOCK_PERIOD: 100
pdk::sky130A:
  MAX_FANOUT_CONSTRAINT: 6
  FP_CORE_UTIL: 40
  PL_TARGET_DENSITY_PCT: expr::($FP_CORE_UTIL + 10.0)
  scl::sky130_fd_sc_hd:
    CLOCK_PERIOD: 15.0
```

--------------------------------

### Install Dependencies with Homebrew

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/installation_macos.md

Installs necessary packages like make, Python, and Docker using Homebrew. Ensure Homebrew is installed first.

```shell
brew install make python python-tk
brew install --cask docker
```

--------------------------------

### Install curl on Ubuntu

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/nix_installation/installation_linux.md

Ensures `curl` is installed, which is a prerequisite for downloading and running the Nix installation script.

```bash
sudo apt-get install -y curl
```

--------------------------------

### Pin Placement Configuration Example

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/reference/pin_placement_cfg.md

Example .cfg file demonstrating section definitions, pin regular expressions, virtual pins, and annotations for the SPM design.

```cfg
#N
@min_distance=0.1
x.*

#S
$1
rst

#E
clk

#W
p
y

```

--------------------------------

### Install Ubuntu on WSL

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/installation_win.md

Use this command in Windows PowerShell to install the Ubuntu distribution for WSL.

```powershell
wsl --install -d Ubuntu
```

--------------------------------

### Minimal JSON Configuration Example

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/reference/configuration.md

A basic JSON configuration file demonstrating essential design parameters and PDK-specific settings.

```json
{
  "DESIGN_NAME": "spm",
  "VERILOG_FILES": "dir::src/*.v",
  "CLOCK_PORT": "clk",
  "CLOCK_PERIOD": 100,
  "pdk::sky130A": {
    "MAX_FANOUT_CONSTRAINT": 6,
    "FP_CORE_UTIL": 40,
    "PL_TARGET_DENSITY_PCT": "expr::($FP_CORE_UTIL + 10.0)",
    "scl::sky130_fd_sc_hd": {
      "CLOCK_PERIOD": 15.0
    }
  }
}
```

--------------------------------

### Example Timing Path Analysis

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/timing_closure/index.md

This report snippet details a specific timing path, including start and end points, path type, delays, arrival times, required times, and the final slack calculation.

```text
Startpoint: x[9] (input port clocked by clk)
Endpoint: _618_ (rising edge-triggered flip-flop clocked by clk)
Path Group: clk
Path Type: min
Delay Time Description
---------------------------------------------------------
0.00 0.00 clock clk (rise edge)
0.00 0.00 clock network delay (ideal)
0.20 0.20 v input external delay
0.01 0.21 v x[9] (in)
0.08 0.28 ^ _537_/Y (sky130_fd_sc_hd__nand2_1)
0.06 0.34 v _541_/Y (sky130_fd_sc_hd__o21ai_1)
0.00 0.34 v _618_/D (sky130_fd_sc_hd__dfrtp_1)
0.34 data arrival time
0.00 0.00 clock clk (rise edge)
0.00 0.00 clock network delay (ideal)
0.00 0.00 clock reconvergence pessimism
0.00 ^ _618_/CLK (sky130_fd_sc_hd__dfrtp_1)
-0.05 -0.05 library hold time
-0.05 data required time
---------------------------------------------------------
-0.05 data required time
-0.34 data arrival time
---------------------------------------------------------
0.39 slack (MET)

```

--------------------------------

### Run Example Design with OpenLane 1

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/migrants/index.md

In OpenLane 1, example designs were run using './flow.tcl -design spm'. OpenLane 2 uses 'openlane --run-example spm' and copies designs to the current directory.

```bash
./flow.tcl -design spm
```

```bash
openlane --run-example spm
```

--------------------------------

### Instantiate and Run a Flow with Flow.__init__() and Flow.start()

Source: https://context7.com/chipfoundry/openlane2/llms.txt

Initialize a `Flow` object with a configuration and execute its steps using the `start()` method. The `Flow` constructor resolves configuration, and `start()` returns the final `State` after all steps are completed.

```python
from openlane.flows import Flow

Classic = Flow.factory.get("Classic")

```

--------------------------------

### Install Docker Engine on Ubuntu

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/installation_ubuntu.md

Follow these steps to install Docker Engine, CLI, containerd, and Docker Compose plugin. It is recommended to refer to the official Docker documentation for the most up-to-date instructions.

```bash
# Remove old installations
sudo apt-get remove docker docker-engine docker.io containerd runc
# Installation of requirements
sudo apt-get update
sudo apt-get install \
   ca-certificates \
   curl \
   gnupg \
   lsb-release
# Add the keyrings of docker
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# Add the package repository
echo \
   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Update the package repository
sudo apt-get update

# Install Docker
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Check for installation
sudo docker run hello-world
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/installation_linux.md

Run this command to confirm that Docker has been installed correctly. It pulls and runs a minimal 'hello-world' container.

```bash
sudo docker run hello-world
```

--------------------------------

### Install Nix with OpenLane Configuration

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/nix_installation/installation_win.md

This command installs Nix using the Determinate Systems installer script. It configures Nix to use the OpenLane cachix binary cache for faster builds. Ensure you close and reopen your Ubuntu terminal after installation.

```bash
$ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install --no-confirm --extra-conf "
    extra-substituters = https://openlane.cachix.org
    extra-trusted-public-keys = openlane.cachix.org-1:qqdwh+QMNGmZAuyeQJTH9ErW57OWSvdtuwfBKdS254E=
"
```

--------------------------------

### Flow.__init__() and Flow.start()

Source: https://context7.com/chipfoundry/openlane2/llms.txt

The Flow constructor accepts a config path/dict and resolves configuration; start() executes all steps and returns the final State.

```APIDOC
## Flow.__init__() and Flow.start() — Instantiate and Run a Flow

### Description
The `Flow` constructor accepts a config path/dict and resolves configuration; `start()` executes all steps and returns the final `State`.

### Method Signature
```python
Flow(config_path_or_dict, flow_name)
Flow.start()
```

### Parameters
- **config_path_or_dict**: Path to a configuration file or a dictionary containing configuration variables.
- **flow_name**: The name of the flow to instantiate (e.g., "Classic").

### Request Example
```python
from openlane.flows import Flow

Classic = Flow.factory.get("Classic")

# Instantiate the flow with a configuration file
flow = Classic("~/my_designs/pm32/config.json")

# Execute the flow
final_state = flow.start()

# Instantiate the flow with a configuration dictionary
config_dict = {
    "DESIGN_NAME": "inverter",
    "VERILOG_FILES": ["/path/to/inv.v"],
    "CLOCK_PERIOD": 10,
    "CLOCK_PORT": "clk",
}
flow2 = Classic(config_dict)
final_state2 = flow2.start()
```

### Response Example
```json
{
  "state": {
    "design_name": "pm32",
    "metrics": {
      "timing_slew_violation": 0,
      "timing_setup_violation": 0
    },
    "views": {
      "verilog": "/path/to/run/results/final.v",
      "def": "/path/to/run/results/final.def"
    }
  }
}
```
```

--------------------------------

### Instantiate and Start Custom Flow Using API

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/writing_custom_flows.md

Instantiate and start a custom flow defined via the API. The `start` method returns the final state and a list of step objects. Avoid calling the `run` method directly, as it is intended for internal use by the `Flow` class.

```python
flow = MyFlow(
    {
        "PDK": "sky130A",
        "DESIGN_NAME": "spm",
        "VERILOG_FILES": ["./src/spm.v"],
        "CLOCK_PORT": "clk",
        "CLOCK_PERIOD": 10,
    },
    design_dir=".",
)
flow.start()
```

--------------------------------

### Docker Hello-World Output

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/installation_linux.md

The expected output after a successful Docker installation when running the 'hello-world' container.

```text
Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (amd64)
3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
https://hub.docker.com/

For more examples and ideas, visit:
https://docs.docker.com/get-started/

```

--------------------------------

### Install Nix on macOS

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/nix_installation/installation_macos.md

Run this command in Terminal.app to install Nix with specific configurations for OpenLane. Ensure you close all terminals after completion.

```bash
$ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install --no-confirm --extra-conf "
    extra-substituters = https://openlane.cachix.org
    extra-trusted-public-keys = openlane.cachix.org-1:qqdwh+QMNGmZAuyeQJTH9ErW57OWSvdtuwfBKdS254E="

```

--------------------------------

### Install Ubuntu Development Packages

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/_ubuntu_packages.md

Update package lists, upgrade existing packages, and install essential development tools including build tools, Python, pip, venv, curl, make, and git.

```bash
sudo apt-get update
sudo apt-get upgrade
sudo apt install -y build-essential python3 python3-venv python3-pip python3-tk curl make git
```

--------------------------------

### OpenLane 1 Macro Configuration Example

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/migrants/variables.md

Illustrates how macro information was defined across multiple variables in OpenLane 1.

```json
{
  "VERILOG_FILES_BLACKBOX": ["dir::macros/spm/nl/spm.nl.v"],
  "EXTRA_GDS_FILES": ["dir::macros/gds/spm.gds"],
  "EXTRA_LEFS": ["dir::macros/lef/spm.lef"],
  "EXTRA_SPEFS": "spm dir::macros/spm/spef/nom_/spm.nom.spef dir::macros/spm/spef/nom_/spm.nom.spef dir::macros/spm/spef/nom_/spm.max.spef",
  "MACRO_PLACEMENT_CFG": "dir::macro_placement.cfg"
}
```

--------------------------------

### WSL Verbose Output - Ubuntu Running

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/installation_win.md

Example output indicating that Ubuntu and Docker services are running correctly within WSL.

```powershell
PS C:\Users\user> wsl --list --verbose
NAME                   STATE           VERSION
* Ubuntu                 Running         2
docker-desktop         Running         2
docker-desktop-data    Running         2
```

--------------------------------

### Instantiate and Run Classic Flow

Source: https://context7.com/chipfoundry/openlane2/llms.txt

Instantiate the Classic flow with a configuration file, PDK, and PDK root. The start method runs the flow and returns the final state, providing paths to GDSII, netlists, and design metrics.

```python
flow = Classic(
    config="~/my_designs/pm32/config.json",
    pdk="sky130A",
    pdk_root="~/.volare",
)

final_state = flow.start(
    tag="my_run_01",   # optional: name the run directory
    overwrite=False,   # set True to delete and re-run an existing tag
)

print(final_state["gds"])
print(final_state["nl"])
print(final_state.metrics.get("design__instance__area"))
```

--------------------------------

### Run Docker Hello World

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/_common.md

Execute the 'hello-world' Docker image to confirm Docker is functioning. This command should run without requiring root privileges after initial setup.

```shell
# After reboot
docker run hello-world
```

--------------------------------

### CVC Timing Violation Message Example

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/timing_closure/index.md

This is an example of a timing violation message that CVC might display during simulation, indicating a potential issue with setup or hold times.

```text
WARN** now 2050218 ps [566] timing violation in
x.y.sky130_fd_sc_hd__dfxtp_1_0_ (diff. 11 ps)

setup(of setuphold)((posedge D):2050207 ps, (posedge CLK):2050218 ps, 76 ps);
```

--------------------------------

### Install curl on Ubuntu

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/nix_installation/installation_win.md

Before installing Nix, ensure curl is installed on your Ubuntu WSL distribution. This command uses apt-get to install curl.

```bash
$ sudo apt-get install -y curl
```

--------------------------------

### Verify OpenLane Installation

Source: https://github.com/chipfoundry/openlane2/blob/main/notebook.ipynb

Prints the installed version of the OpenLane library to verify the installation.

```python
import openlane

print(openlane.__version__)

```

--------------------------------

### Classic Flow Instantiation and Execution

Source: https://context7.com/chipfoundry/openlane2/llms.txt

Demonstrates how to instantiate the Classic flow with a configuration file and run it. It also shows how to access the final state, including GDSII path, netlist, and design metrics.

```APIDOC
## Classic Flow

### Description
Instantiate and run the Classic flow.

### Method
`Classic(config, pdk, pdk_root)`

### Parameters
- **config** (string) - Path to the configuration JSON file.
- **pdk** (string) - The PDK to use (e.g., "sky130A").
- **pdk_root** (string) - The root directory for the PDK.

### Method
`start(tag, overwrite)`

### Parameters
- **tag** (string, optional) - Name for the run directory.
- **overwrite** (boolean, optional) - Set to `True` to delete and re-run an existing tag. Defaults to `False`.

### Response
- **final_state** (dict) - A dictionary containing the final state of the flow.
  - **gds** (string) - Path to the final GDSII file.
  - **nl** (string) - Path to the gate-level netlist.
  - **metrics** (dict) - Dictionary of design metrics.

### Request Example
```python
from openlane.flows import Classic

flow = Classic(
    config="~/my_designs/pm32/config.json",
    pdk="sky130A",
    pdk_root="~/.volare",
)

final_state = flow.start(
    tag="my_run_01",
    overwrite=False,
)

print(final_state["gds"])
print(final_state["nl"])
print(final_state.metrics.get("design__instance__area"))
```
```

--------------------------------

### Install OpenLane using PIP

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/_common.md

Install the OpenLane package using pip. This command downloads and installs the latest version of OpenLane.

```shell
python3 -m pip install openlane
```

--------------------------------

### Get and Display Step Help

Source: https://github.com/chipfoundry/openlane2/blob/main/notebook.ipynb

Retrieve a specific implementation step, such as Yosys Synthesis, from the step factory and display its available configuration options and help information.

```python
from openlane.steps import Step

Synthesis = Step.factory.get("Yosys.Synthesis")

Synthesis.display_help()
```

--------------------------------

### Download and Install OpenLane

Source: https://github.com/chipfoundry/openlane2/blob/main/notebook.ipynb

Downloads and installs OpenLane, its tool dependencies using Nix, and OpenLane itself using PIP. Ensure `python3-tk` is installed on your OS if needed.

```python
# @title Get OpenLane {display-mode: "form"}
# @markdown Click the ▷ button to download and install OpenLane.
# @markdown
# @markdown This will install OpenLane's tool dependencies using Nix,
# @markdown and OpenLane itself using PIP.
# @markdown
# @markdown Note that `python3-tk` may need to be installed using your OS's
# @markdown package manager.
import os
import subprocess
import IPython

openlane_version = "version-2.1"  # @param {key:"OpenLane Version", type:"string"}

if openlane_version == "latest":
    openlane_version = "main"

pdk_root = "~/.volare"  # @param {key:"PDK Root", type:"string"}

pdk_root = os.path.expanduser(pdk_root)

pdk = "sky130"  # @param {key:"PDK (without the variant)", type:"string"}

openlane_ipynb_path = os.path.join(os.getcwd(), "openlane_ipynb")

display(IPython.display.HTML("<h3>Downloading OpenLane…</a>"))


TESTING_LOCALLY = False
!rm -rf {openlane_ipynb_path}
!mkdir -p {openlane_ipynb_path}
if TESTING_LOCALLY:
    !ln -s {os.getcwd()} {openlane_ipynb_path}
else:
    !curl -L "https://github.com/efabless/openlane2/tarball/{openlane_version}" | tar -xzC {openlane_ipynb_path} --strip-components 1

try:
    import tkinter
except ImportError:
    if "google.colab" in sys.modules:
        !sudo apt-get install python-tk

try:
    import tkinter
except ImportError as e:
    display(
        IPython.display.HTML(
            '<h3 style="color: #800020";>❌ Failed to import the <code>tkinter</code> library for Python, which is required to load PDK configuration values. Make sure <code>python3-tk</code> or equivalent is installed on your system.</a>'
        )
    )
    raise e from None


display(IPython.display.HTML("<h3>Downloading OpenLane's dependencies…</a>"))
try:
    subprocess.check_call(
        ["nix", "profile", "install", ".#colab-env", "--accept-flake-config"],
        cwd=openlane_ipynb_path,
    )
except subprocess.CalledProcessError as e:
    display(
        IPython.display.HTML(
            '<h3 style="color: #800020";>❌ Failed to install binary dependencies using Nix…</h3>'
        )
    )

display(IPython.display.HTML("<h3>Downloading Python dependencies using PIP…</a>"))
try:
    subprocess.check_call(
        ["pip3", "install", "."],
        cwd=openlane_ipynb_path,
    )
except subprocess.CalledProcessError as e:
    display(
        IPython.display.HTML(
            '<h3 style="color: #800020";>❌ Failed to install Python dependencies using PIP…</h3>'
        )
    )
    raise e from None

display(IPython.display.HTML("<h3>Downloading PDK…</a>"))
import volare

volare.enable(
    volare.get_volare_home(pdk_root),
    pdk,
    open(
        os.path.join(openlane_ipynb_path, "openlane", "open_pdks_rev"),
        encoding="utf8",
    )
    .read()
    .strip(),
)

sys.path.insert(0, openlane_ipynb_path)
display(IPython.display.HTML("<h3>⭕️ Done.</a>"))

import logging

# Remove the stupid default colab logging handler
logging.getLogger().handlers.clear()

```

--------------------------------

### Install Nix with OpenLane Cache

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/nix_installation/installation_linux.md

Installs Nix using the Determinate Systems installer script. It configures Nix to use the OpenLane cache for faster access to required packages and specifies TLS version and security protocols.

```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install --no-confirm --extra-conf "
    extra-substituters = https://openlane.cachix.org
    extra-trusted-public-keys = openlane.cachix.org-1:qqdwh+QMNGmZAuyeQJTH9ErW57OWSvdtuwfBKdS254E=
"
```

--------------------------------

### Netgen LVS Report Example

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/caravel/index.md

This is an example of a clean LVS report from Netgen, confirming circuit equivalence.

```text
Cell pin lists are equivalent.
Device classes user_project_wrapper and user_project_wrapper are equivalent.

Final result: Circuits match uniquely.


```

--------------------------------

### Build Documentation Locally

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/contributors/docs.md

Builds the documentation locally using Sphinx. Ensure you are in the OpenLane/ directory and the virtual environment is activated.

```sh
cd OpenLane/
make docs
```

--------------------------------

### Optimizing Flow Example

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/writing_custom_flows.md

This is a demo flow built on the principle of running steps asynchronously. It works across two stages: Synthesis Exploration and Floorplanning and Placement, demonstrating parallel step execution and fallback strategies.

```python
import typing

from openlane.flows import Flow
from openlane.steps import Step


class OptimizingFlow(Flow):
    Steps = {
        "synthesis": Yosys.Synthesis,
        "floorplan": OpenROAD.Floorplan,
        "place": OpenROAD.Place,
        "cts": OpenROAD.CTS,
        "timing_ அறிகுற": OpenROAD.TimingAnalyze,
        "power_analysis": OpenROAD.PowerAnalyze,
    }

    def run(self) -> typing.Tuple[str, typing.List[Step]]:
        # Synthesis Exploration
        synthesis_strategies = [
            Yosys.Synthesis(config=self.config.copy(SYNTH_STRATEGY="flow"), state_in=self.state_in),
            Yosys.Synthesis(config=self.config.copy(SYNTH_STRATEGY="timing"), state_in=self.state_in),
            Yosys.Synthesis(config=self.config.copy(SYNTH_STRATEGY="area"), state_in=self.state_in),
        ]

        # Run synthesis strategies in parallel
        synthesis_futures = [
            self.start_step_async(step)
            for step in synthesis_strategies
        ]

        # Wait for all synthesis strategies to complete and find the best one
        best_synthesis_state = None
        best_synthesis_step = None
        min_area = float("inf")

        for future in synthesis_futures:
            state, step = future.result()
            if step.config.get("SYNTH_STRATEGY") == "area":
                if state.design_area < min_area:
                    min_area = state.design_area
                    best_synthesis_state = state
                    best_synthesis_step = step

        # Floorplanning and Placement
        floorplan_config = self.config.copy(FP_CORE_UTIL=90)
        floorplan = OpenROAD.Floorplan(
            config=floorplan_config,
            state_in=best_synthesis_state,
        )
        floorplan_future = self.start_step_async(floorplan)

        # Try high utilization first
        try:
            floorplan_state, floorplan_step = floorplan_future.result()
        except DeferredStepError as e:
            # If high utilization fails, fall back to lower utilization
            self.log(f"High utilization floorplanning failed: {e}. Falling back to lower utilization.")
            floorplan_config = self.config.copy(FP_CORE_UTIL=80)
            floorplan = OpenROAD.Floorplan(
                config=floorplan_config,
                state_in=best_synthesis_state,
            )
            floorplan_state, floorplan_step = self.start_step(floorplan)

        # Placement
        place = OpenROAD.Place(config=self.config, state_in=floorplan_state)
        place_state, place_step = self.start_step(place)

        # CTS
        cts = OpenROAD.CTS(config=self.config, state_in=place_state)
        cts_state, cts_step = self.start_step(cts)

        # Timing Analysis
        timing_analyze = OpenROAD.TimingAnalyze(config=self.config, state_in=cts_state)
        timing_analyze_state, timing_analyze_step = self.start_step(timing_analyze)

        # Power Analysis
        power_analyze = OpenROAD.PowerAnalyze(config=self.config, state_in=timing_analyze_state)
        power_analyze_state, power_analyze_step = self.start_step(power_analyze)

        return power_analyze_state, [
            best_synthesis_step,
            floorplan_step,
            place_step,
            cts_step,
            timing_analyze_step,
            power_analyze_step,
        ]


@Flow.factory.register()
class OptimizingFlowFactory:
    def __call__(self, *args, **kwargs) -> OptimizingFlow:
        return OptimizingFlow(*args, **kwargs)

```

--------------------------------

### Check Installation Versions

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/_common.md

Verify that Docker, Python 3, and pip are installed and check their respective versions. This ensures compatibility with OpenLane.

```shell
docker --version
python3 --version
python3 -m pip --version
```

```shell
$ docker --version
Docker version 27.3.1, build ce12230
$ python3 --version
Python 3.10.5
$ python3 -m pip --version
pip 21.0 from /usr/lib/python3.10/site-packages/pip (python 3.10)
...
```

--------------------------------

### Install Cachix with Nix

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/nix_installation/_common.md

Installs the Cachix tool, which is used to manage binary caches for Nix. This is a prerequisite for using pre-built OpenLane dependencies.

```bash
$ nix-env -f "<nixpkgs>" -iA cachix
```

--------------------------------

### OpenLane Design Configuration File Example

Source: https://context7.com/chipfoundry/openlane2/llms.txt

A sample JSON file defining variables for an ASIC design flow. This includes design name, Verilog files, clock parameters, utilization targets, and flags for running specific flow steps.

```json
{
  "meta": {
    "version": 2
  },
  "DESIGN_NAME": "pm32",
  "VERILOG_FILES": ["dir::pm32.v", "dir::spm.v"],
  "CLOCK_PERIOD": 25,
  "CLOCK_PORT": "clk",
  "FP_CORE_UTIL": 45,
  "FP_PIN_ORDER_CFG": "dir::pin_order.cfg",
  "RUN_CTS": true,
  "RUN_MAGIC_DRC": true,
  "RUN_LVS": true,
  "RUN_SPEF_EXTRACTION": true,
  "SYNTH_STRATEGY": "AREA 0",
  "CLOCK_NET": "clk"
}
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/installation_ubuntu.md

This output indicates that your Docker installation is successful. It confirms that the Docker client can communicate with the Docker daemon and pull images.

```text
Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (amd64)
3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
https://hub.docker.com/

For more examples and ideas, visit:
https://docs.docker.com/get-started/
```

--------------------------------

### Install OpenLane (Python-only)

Source: https://github.com/chipfoundry/openlane2/blob/main/Readme.md

Use this command to install OpenLane using only Python. This method is advanced and not recommended, as you will need to provide your own compiled utilities.

```sh
python3 -m pip install --upgrade openlane
```

--------------------------------

### Create Design Directory

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/newcomers/index.md

Create a directory to house your design source files. This is the first step before adding configuration and RTL.

```bash
[nix-shell:~/openlane2]$ mkdir -p ~/my_designs/pm32
```

--------------------------------

### Execute an Optimizing Flow

Source: https://context7.com/chipfoundry/openlane2/llms.txt

Demonstrates how to instantiate and run the built-in 'Optimizing' flow, which explores multiple synthesis strategies in parallel and selects the best result. It also shows how to access metrics from the final state.

```python
from openlane.flows import Flow

Optimizing = Flow.factory.get("Optimizing")

flow = Optimizing(
    config="~/my_designs/pm32/config.json",
    pdk="sky130A",
    pdk_root="~/.volare",
)

final_state = flow.start(tag="optimizing_run")

print(final_state.metrics.get("design__instance__area"))
```

--------------------------------

### Run OpenLane Smoke Test

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/getting_started/common/docker_installation/_common.md

Execute a smoke test to ensure OpenLane is installed correctly and its Docker environment is functional. This is a basic test to confirm the installation.

```shell
python3 -m openlane --dockerized --smoke-test
```

--------------------------------

### Instantiate and Use Steps in a Flow

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/writing_custom_flows.md

Demonstrates how to instantiate and call steps within the `run` method of a custom flow. Ensure that `config` and `state_in` are correctly provided.

```python
synthesis = Yosys.Synthesis(
    config=self.config,
    state_in=...,
)
synthesis.start()

sdc_load = OpenROAD.CheckSDCFiles(
    config=self.config,
    state_in=synthesis.state_out,
)
```

--------------------------------

### Build and Save State Updates

Source: https://context7.com/chipfoundry/openlane2/llms.txt

Demonstrates how to create a new state by overriding existing properties and saving the updated state to a snapshot directory. Also shows serialization and deserialization of the state.

```python
state_updated = State(
    state_post_synth,
    overrides={
        DesignFormat.DEF: "/path/to/design.def"
    },
    metrics=GenericImmutableDict(
        state_post_synth.metrics,
        overrides={"design__die__area": "1000.0"},
    ),
)

state_updated.save_snapshot("/path/to/snapshot")

json_str = state_updated.dumps()
restored = State.loads(json_str)
```

--------------------------------

### Running OpenLane Flow

Source: https://github.com/chipfoundry/openlane2/blob/main/docs/source/usage/caravel/index.md

This command initiates the OpenLane synthesis and implementation flow using a specified configuration file. Ensure you are within the `nix-shell` environment before execution.

```bash
[nix-shell:~/openlane2]$ openlane ~/caravel_aes_accelerator/openlane/user_project_wrapper/config.json
```