haadic 0.6.0__py3-none-any.whl

haadic/__init__.py

@@ -0,0 +1,21 @@
+"""
+A Python framework for analog IC design automation.
+
+# Haadic structure:
+
+ - core
+    - flow: for defining and running design flows
+    - steps: for defining the core steps in the design flow, such as layout generation, extraction, simulation, etc.
+    - techno: for handling technology-specific information and operations.
+ - io
+    - readers: files readers (spice, raw, etc.)
+    - writers: files writers (spice)
+    - wrappers: for external tools (e.g., magic, netgen, etc.)
+ - design
+    - layouts: for layout generation and manipulation
+    - models: for device and circuit modeling
+    - evaluators: for performance evaluation
+    - components: parameterized components (e.g., common sources) and design helpers (e.g., EKV model).
+"""
+
+name = "haadic"

haadic/_config.py

@@ -0,0 +1,5 @@
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).parent
+DATA_DIR = ROOT_DIR / "data"
+REF_PATH = ROOT_DIR.parent / "tests" / "ref_files"

haadic/core/__init__.py

@@ -0,0 +1 @@
+"""Module for the haadic core functionality: run analog flow."""

haadic/core/flow.py

@@ -0,0 +1,111 @@
+"""Module defining the Flow class, which composes multiple steps (layout generation, extraction, simulation, post-processing) into a complete design flow."""
+
+import logging
+from pathlib import Path
+from typing import Callable, Iterable
+from dataclasses import dataclass, field
+from tabulate import tabulate
+
+import haadic.core.steps.step as step
+from haadic.core.steps.extraction import Extract, ConfigExtract
+from haadic.core.steps.layout_generation import Layout, ConfigLayout, LayoutFunc
+from haadic.core.steps.spice_simulation import BenchSim, ConfigSim
+from haadic.core.steps.post_process import PostProcess, ConfigPostProc, PostProcessFunc
+from haadic.core.techno import Available_PDK
+from haadic.io.wrappers.magic import ExtractLevels
+
+
+@dataclass
+class ConfigFlow:
+    """
+    Configuration for a Flow execution.
+
+    :param techno: Selected PDK name.
+    :param reload: Whether to reload intermediate files when available (e.g., layout, spice netlist) or to recompute them.
+    :param run_dir: Base directory where results are written.
+    :param extract_level: Extraction level used by the Extract step.
+    :param sweep_folder: If True, create a separate folder per sweep value when using the run_from_* methods.
+    """
+
+    techno: Available_PDK = "sky130"
+    reload: bool = True
+    run_dir: Path = Path("./results")
+    extract_level: ExtractLevels = "RC"
+    sweep_folder: bool = True
+
+
+@dataclass
+class Flow:
+    """
+    Flow dataclass.
+
+    :param layout: function that generates the layout. It takes as argument a klayout Cell, a LayerStack and the dimensions of the layout to generate.
+     It should return a klayout Cell with the generated layout.
+    :param benches: list of bench files to run. The flow will look for these files in the current folder and run them with the extracted spice netlist.
+     They can be absolute or relative to the running folder.
+    :param postprocess: function that evaluates the performances of the circuit. It takes as argument the simulation results of the benches and the dimensions of the layout.
+     It should return a dictionary with the performance metrics to optimize as keys and their values as values.
+    :param config: flow options, such as the technology to use, whether to reload the layout if it already exists, and the folder to run the flow in.
+    """
+
+    layout: LayoutFunc
+    benches: Iterable[Path]
+    postprocess: Iterable[PostProcessFunc]
+    config: ConfigFlow = field(default_factory=ConfigFlow)
+
+    def run_from_dim(self, dimensions: step.Dim) -> step.Dim:
+        """
+        Run the composed flow starting from explicit dimensions.
+
+        Args:
+            dimensions: a `Dim` instance describing layout dimensions/parameters.
+
+        Returns:
+            A `Dim`-like object containing aggregated performance metrics produced by the postprocess steps.
+
+        """
+        datas = step.Dim()
+        d_benches = [f.resolve() for f in self.benches]
+        for bench, eval in zip(d_benches, self.postprocess):
+            start = step.init_step(
+                dimensions, self.config.run_dir, self.config.sweep_folder
+            )
+            flow = step.compose(
+                Layout(ConfigLayout(self.layout, self.config.techno)),
+                Extract(ConfigExtract(self.config.techno, self.config.extract_level)),
+                BenchSim(ConfigSim(bench, self.config.techno)),
+                reload=self.config.reload,
+            )
+            output_file = flow.run(start)
+            pp = PostProcess(ConfigPostProc(eval))
+            data = pp.run(output_file, dimensions)
+            for key in data.dct:
+                datas[key] = data[key]
+        return datas
+
+    def run_from_target(
+        self,
+        target: step.Dim,
+        local_model: Callable[[step.Dim], step.Dim],
+    ) -> step.Dim:
+        """
+        Run the flow from a target specification using a local model.
+
+        Args:
+            target: A `Dim` describing desired target values.
+            local_model: Callable that maps the `target` to actual layout `Dim` parameters.
+
+        Returns:
+            A `Dim`-like object containing aggregated performance metrics produced by the postprocess steps.
+
+        """
+        perf = self.run_from_dim(local_model(target))
+        res = [(key, perf.dct[key], target.dct.get(key, "N/A")) for key in perf.dct]
+        logging.info(
+            "\n" + tabulate(res, headers=["obtained", "targeted"], tablefmt="grid")
+        )
+
+        logging.info("compare performances to targets")
+        cost = step.compare_to(perf.dct, target.dct)
+        logging.info(f"current cost: {cost}")
+        return perf

haadic/core/steps/__init__.py

@@ -0,0 +1 @@
+"""Module for the core steps in the design flow."""

haadic/core/steps/extraction.py

@@ -0,0 +1,53 @@
+"""Module defining the Extract step, which performs layout extraction to generate a SPICE netlist from a GDSII layout."""
+
+from haadic.core.steps.step import Step
+from dataclasses import dataclass, field
+from typing import Sequence
+from haadic.io.wrappers.magic import ExtractLevels, extract_spice
+from pathlib import Path
+from haadic.core.techno import get_file, Available_PDK
+
+
+@dataclass
+class ConfigExtract:
+    """
+    Configuration for the Extract step.
+
+    :param techno: technology to use for extraction (e.g., "sky130", "gf180mcu").
+    :param level: extraction level to use (e.g., "NoPar", "RC").
+    """
+
+    techno: Available_PDK = "sky130"
+    level: ExtractLevels = "RC"
+
+
+@dataclass
+class Extract(Step):
+    """
+    Extract step dataclass.
+
+    :param config: configuration for the Extract step, including the technology to use and the extraction level.
+    :param input_suffixes: list of suffixes for the expected input file(s) (default: [".gds"]).
+    :param output_suffix: suffix for the output file (default: ".cir").
+    """
+
+    config: ConfigExtract = field(default_factory=ConfigExtract)
+    input_suffixes: Sequence[str] = field(default_factory=lambda: [".gds"])
+    output_suffix: str = ".cir"
+
+    def run(self, input_file: Path = Path("top.gds")) -> Path:
+        """
+        Extract a netlist from a given layout.
+
+        :param Path input_file: input gds file.
+        :return Path: extracted spice circuit.
+        """
+        output_path = self.output_file(input_file)
+        rc_file = get_file(self.config.techno, "magic_rc")
+        return extract_spice(
+            input_file,
+            rc_file,
+            input_file.stem,
+            output_path,
+            options=self.config.level,
+        )

haadic/core/steps/layout_generation.py

@@ -0,0 +1,59 @@
+"""Module defining the Layout step for generating layouts from parametric descriptions."""
+
+import logging
+from haadic.core.techno import Available_PDK
+from pathlib import Path
+from typing import Callable, Sequence
+from dataclasses import field, dataclass
+import json
+
+from haadic.design.layouts.base_cell import BaseCell
+from haadic.core.steps.step import Dim, Step
+
+type LayoutFunc = Callable[[BaseCell, Dim], BaseCell]
+
+
+@dataclass
+class ConfigLayout:
+    """
+    Configuration for the Layout step.
+
+    :param layout: function that generates the layout.
+    :param techno: technology to be used.
+    """
+
+    layout: LayoutFunc
+    techno: Available_PDK = "sky130"
+
+
+@dataclass
+class Layout(Step):
+    """
+    Step to generate a layout from a parametric description.
+
+    :param config: configuration for the layout generation step, including the layout function and the technology to use.
+    :param input_suffixes: list of expected suffixes for the input files. By default, it is set to [".json"].
+    :param output_suffix: suffix for the output file. By default, it is set to ".gds".
+    """
+
+    config: ConfigLayout
+    input_suffixes: Sequence[str] = field(default_factory=lambda: [".json"])
+    output_suffix: str = ".gds"
+
+    def run(self, input_file: Path) -> Path:
+        """
+        Generate a layout in the requested techologies with the given parametric layout and the given set of parameters.
+
+        :param input_file: set of parameters for the layout.
+        """
+        with input_file.open() as f:
+            dimensions = json.load(f)
+        output_file = self.output_file(input_file)
+        logging.info("layout generation with geometry: " + str(dimensions))
+
+        cellb = BaseCell(self.config.techno, input_file.stem)
+
+        self.config.layout(cellb, dimensions)
+
+        cellb.write(output_file)
+        return output_file

haadic/core/steps/post_process.py

@@ -0,0 +1,58 @@
+"""Module defining the PostProcess step for post-processing simulation results and extracting performance metrics."""
+
+from haadic.io.readers.raw import parse_out
+from typing import Callable, Sequence
+from dataclasses import field, dataclass
+from pathlib import Path
+import pandas as pd
+
+from haadic.core.steps.step import Dim
+
+SimRes = pd.DataFrame
+
+type PostProcessFunc = Callable[[SimRes, Dim, Path], Dim]
+
+
+@dataclass
+class ConfigPostProc:
+    """
+    Configuration for the PostProcess step.
+
+    :param evaluate: function that evaluates the performances of the circuit.
+        It takes as argument the simulation results of the benches and the dimensions of the layout.
+        It should return a Dim class with the performance metrics.
+    """
+
+    evaluate: PostProcessFunc
+
+
+@dataclass
+class PostProcess:
+    """
+    Step to post-process the simulation results and extract performance metrics.
+
+    This step is meant to be run after a spice simulation step, and it takes as input the raw output file of the simulation (with suffix .raw)
+    and produces as output a Dim class with the performance metrics.
+
+    :param config: configuration for the post-processing step.
+    :param input_suffixes: list of expected suffixes for the input files. By default, it is set to [".raw"].
+    :param output_suffix: suffix for the output file. By default, it is set to "".
+    """
+
+    config: ConfigPostProc
+    input_suffixes: Sequence[str] = field(default_factory=lambda: [".raw"])
+    output_suffix: str = ""
+
+    def run(self, data_file: Path = Path("top.raw"), dimensions: Dim = Dim()) -> Dim:
+        """
+        Run the post-processing step.
+
+        This method reads the raw simulation output file, evaluates the performance metrics using the provided evaluate function, and returns a Dim class with the performance metrics.
+
+        :param data_file: path to the raw simulation output file.
+        :param dimensions: dimensions of the layout.
+        :return Dim: performance metrics.
+        """
+        data = parse_out(data_file)
+        base_dir = data_file.parent
+        return self.config.evaluate(data, dimensions, base_dir)

haadic/core/steps/spice_simulation.py

@@ -0,0 +1,63 @@
+"""Spice simulation step for the haadic design flow."""
+
+from typing import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from haadic.io.handlers.netlist import Netlist
+from haadic.io.wrappers.ngspice import compute
+from haadic.io.wrappers.tools import to_wsl
+from haadic.core.techno import get_file, load_pdk, Available_PDK
+from haadic.core.steps.step import can_skip, Step
+
+
+@dataclass
+class ConfigSim:
+    """
+    Configuration for the BenchSim step.
+
+    :param bench: path to the bench file to simulate, defaults to "bench.cir"."
+    :param techno: name of the technology to use for the simulation, defaults to "sky130".
+    """
+
+    bench: Path = Path("bench.cir")
+    techno: Available_PDK = "sky130"
+
+
+@dataclass
+class BenchSim(Step):
+    """
+    Step to run a spice simulation using ngspice.
+
+    :param config: configuration for the BenchSim step.
+    :param input_suffixes: list of accepted input file suffixes for this step, defaults to [".cir"].
+    :param output_suffix: suffix for the output file generated by this step, defaults to ".raw".
+    """
+
+    config: ConfigSim = field(default_factory=ConfigSim)
+    input_suffixes: Sequence[str] = field(default_factory=lambda: [".cir"])
+    output_suffix: str = ".raw"
+
+    def run(self, input_file: Path = Path("top.cir")) -> Path:
+        """
+        Run the given netlist using the requested technologie.
+
+        :param input_file: spice netlist bench to be simulated, defaults to "bench.cir"
+        :return Path: path to the output raw file generated by ngspice.
+        """
+        bench = self.config.bench
+        data_file = (
+            Path(input_file).with_name(bench.name).with_suffix(self.output_suffix)
+        )
+        if can_skip(bench, data_file) and can_skip(input_file, data_file):
+            return data_file
+        techno = self.config.techno
+
+        spice = Netlist().load(bench)
+        section = load_pdk(techno).get("section", "tt")
+        spice.add_lib(to_wsl(get_file(techno, "lib_spice")), section)
+
+        spice.add_include(input_file)
+        spice.write(data_file.with_name(bench.name))
+
+        compute(data_file.with_name(bench.name), data_file)
+        return data_file

haadic/core/steps/step.py

@@ -0,0 +1,226 @@
+"""Module defining the Step protocol and related utilities for managing steps in the haadic flow."""
+
+import json
+from functools import reduce
+from typing import Any, Protocol, Sequence
+import logging
+import os
+from pathlib import Path
+import shutil
+
+import pydantic
+
+
+@pydantic.dataclasses.dataclass
+class Dim:
+    """
+    Simple container for named dimension/performance values.
+
+    Stores a mapping of string keys to float values and provides convenient
+    accessors used throughout the flow (indexing, stringification).
+    """
+
+    dct: dict[str, float] = pydantic.Field(default_factory=dict)
+
+    def __getitem__(self, key: str) -> float:
+        """Get the value corresponding to the given key."""
+        return self.dct[key]
+
+    def __setitem__(self, key: str, value: float) -> None:
+        """Set the value corresponding to the given key."""
+        self.dct[key] = float(value)
+
+    def __str__(self) -> str:
+        """
+        Get a string representation of the dimensions, in the format "key1_value1__key2_value2".
+
+        This format is used for naming files and folders corresponding to specific dimension values.
+        """
+        return "__".join([f"{key}_{value:g}" for key, value in self.dct.items()])
+
+
+class Step(Protocol):
+    """
+    Class storing information for a step.
+
+    Each step of a Flow should be implemented as a class inheriting from Step and implementing the run method, which takes an input file and produces an output file.
+    """
+
+    input_suffixes: Sequence[str]
+    output_suffix: str
+    config: Any
+
+    def output_file(self, input_file: Path) -> Path:
+        """Return the expected output file path for a given input file."""
+        return input_file.with_suffix(self.output_suffix)
+
+    def run(self, input_file: Path) -> Path:
+        """
+        Meta-method to be implemented by each step.
+
+        :param input_file: path to the input file for the step.
+        :return: path to the output file produced by the step.
+        """
+        pass
+
+
+def init_step(dimensions: Dim, base_dir: Path, sweep_folder: bool = False) -> Path:
+    """
+    Create or locate the JSON file representing the initial step for a run.
+
+    The function writes `top.json` in `base_dir` (or in a subfolder named after
+    `dimensions` when `sweep_folder` is True). If an existing file contains the
+    same dimensions it is returned directly.
+
+    Args:
+        dimensions: a `Dim` instance with the design parameters.
+        base_dir: base run directory where `top.json` will be written.
+        sweep_folder: whether to place `top.json` in a subfolder named after `dimensions`.
+
+    Returns:
+        Path to the created or existing `top.json` file.
+
+    """
+    if sweep_folder:
+        output_file = base_dir / dimensions.__str__() / "top.json"
+    else:
+        output_file = base_dir / "top.json"
+    if output_file.is_file():
+        with output_file.open("r") as f:
+            ref = json.load(f)
+        if ref == dimensions.dct:
+            return output_file
+    if not output_file.parent.is_dir():
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+    with output_file.open("w") as f:
+        json.dump(dimensions.dct, f)
+    return output_file
+
+
+def validate_input(input_file: Path, valid_suffixes: Sequence[str]) -> None:
+    """
+    Raise a ValueError if `input_file` does not have an allowed suffix.
+
+    Args:
+        input_file: file to validate.
+        valid_suffixes: sequence of accepted suffix strings (including leading dot).
+
+    """
+    if input_file.suffix not in valid_suffixes:
+        raise ValueError(f"{input_file} suffix is not in {valid_suffixes}")
+
+
+def can_skip(input_file: Path, output_file: Path):
+    """
+    Return True if the step can be skipped based on file modification times.
+
+    A step can be skipped when `output_file` exists and is newer than `input_file`.
+    """
+    if not output_file.is_file():
+        return False
+    if input_file.stat().st_mtime >= output_file.stat().st_mtime:
+        return False
+    return True
+
+
+def compose(*steps: Step, reload: bool = True) -> Step:
+    """
+    Compose multiple Step implementations into a single Step instance.
+
+    The returned object implements the `run(input_file: Path) -> Path` method
+    which will execute each step in order, validating inputs and optionally
+    skipping steps when outputs are up-to-date (controlled by `reload`).
+    """
+
+    class Compose(Step):
+        input_suffixes: Sequence[str]
+        output_suffix: str
+        config: dict[str, Any]
+
+        def __init__(self, config: dict[str, Any]):
+            self.input_suffixes = steps[0].input_suffixes
+            self.output_suffix = steps[-1].output_suffix
+            self.config = config
+
+        def run(self, input_file: Path) -> Path:
+            """
+            Execute the composed steps sequentially starting from `input_file`.
+
+            Args:
+                input_file: initial input file for the first step.
+
+            Returns:
+                Path to the final step's output file.
+
+            """
+
+            def fun(path: Path, step: Step) -> Path:
+                validate_input(path, step.input_suffixes)
+                excepted_output = step.output_file(path)
+                if self.config["reload"] and can_skip(path, excepted_output):
+                    logging.info(
+                        f"Skipping step {step.__class__.__name__} as {excepted_output.name} is up to date with {path.name}"
+                    )
+                    return excepted_output
+                logging.info(
+                    f"Running step {step.__class__.__name__} with input {path.name}"
+                )
+                return step.run(path)
+
+            return reduce(fun, steps, input_file)
+
+    return Compose({"reload": reload})
+
+
+def cleanup(folder: str = "", dry_run: bool = False):
+    """
+    Remove all files generated by haadic in the specified folder.
+
+    :param folder: path of the folder to clean.
+    :param dry_run: if True, only print which files would be removed without actually removing them. Default is False.
+    """
+    suffix_to_remove = [".gds", ".cir", ".raw", ".log", ".nodes", ".sim", ".tcl"]
+    if folder:
+        os.chdir(Path(folder))
+    for suffix in suffix_to_remove:
+        file = Path("top").with_suffix(suffix)
+        if file.is_file():
+            if dry_run:
+                print(f"Would remove file: {file}")
+            else:
+                os.remove(file)
+    directories_to_remove = [
+        "extfile",
+    ]
+    for directory in directories_to_remove:
+        dir_path = Path(directory)
+        if dir_path.is_dir():
+            if dry_run:
+                print(f"Would remove directory: {dir_path}")
+            else:
+                shutil.rmtree(dir_path)
+
+
+def compare_to(perf: dict, target: dict):
+    """
+    Compute a simple squared-error cost between `perf` and `target`.
+
+    Missing keys in `perf` are treated as zero and a warning is emitted.
+
+    Args:
+        perf: dictionary of obtained performance values.
+        target: dictionary of target performance values.
+
+    Returns:
+        Numeric cost (sum of squared errors).
+
+    """
+    cost = 0
+    for key in target:
+        if perf is None or key not in perf:
+            logging.warning(f"Key {key} not found in performance dictionary")
+            cost += target[key] ** 2
+        else:
+            cost += (target[key] - perf[key]) ** 2
+
+    return cost