From cff18e09152c212b7f8cb2f0e2e9d9eabcdabbb2 Mon Sep 17 00:00:00 2001 From: Stefan Holst Date: Tue, 15 Dec 2020 19:20:30 +0900 Subject: [PATCH] start documentation --- .gitignore | 5 +++ README.md | 56 --------------------------------- README.rst | 28 +++++++++++++++++ docs/Makefile | 20 ++++++++++++ docs/conf.py | 64 +++++++++++++++++++++++++++++++++++++ docs/datastructures.rst | 30 ++++++++++++++++++ docs/index.rst | 12 +++++++ docs/parsers.rst | 12 +++++++ docs/simulators.rst | 8 +++++ setup.py | 5 ++- src/kyupy/circuit.py | 70 +++++++++++++++++++++++++++++------------ 11 files changed, 231 insertions(+), 79 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/datastructures.rst create mode 100644 docs/index.rst create mode 100644 docs/parsers.rst create mode 100644 docs/simulators.rst diff --git a/.gitignore b/.gitignore index c563798..1293051 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,8 @@ **/.pytest_cache **/.DS_Store **/*.pyc +docs/_build +build +dist +.idea +src/kyupy.egg-info diff --git a/README.md b/README.md deleted file mode 100644 index 2f11bf1..0000000 --- a/README.md +++ /dev/null @@ -1,56 +0,0 @@ -KyuPy - Processing VLSI Circuits With Ease -========================================== - -KyuPy is a python package for high-performance processing and analysis of -non-hierarchical VLSI designs. Its purpose is to provide a rapid prototyping -platform to aid and accelerate research in the fields of VLSI test, diagnosis -and reliability. KyuPy is freely available under the MIT license. - - -Main Features -------------- - -* Partial [lark](https://github.com/lark-parser/lark) parsers for common files used with synthesized designs: - bench, gate-level verilog, standard delay format (SDF), standard test interface language (STIL) -* Bit-parallel gate-level 2-, 4-, and 8-valued logic simulation -* GPU-accelerated high-throughput gate-level timing simulation -* High-performance through the use of [numpy](https://numpy.org) and [numba](https://numba.pydata.org) - - -Getting Started ---------------- - -KyuPy requires Python 3.6 or newer. -Install the latest release by running: -```commandline -pip3 install --user kyupy -``` -For best performance, ensure you have [numba](https://pypi.org/project/numba) installed: -```commandline -pip3 install --user numba -``` -GPU/CUDA support may [require some additional setup](https://numba.pydata.org/numba-doc/latest/cuda/index.html). -If CUDA or numba is not available, KyuPy will automatically fall back to slow, pure python execution. - -The Jupyter Notebook [UsageExamples.ipynb](https://github.com/s-holst/kyupy/blob/main/UsageExamples.ipynb) on GitHub -contains some useful examples to get familiar with the API. - - -Development ------------ - -To contribute to KyuPy or simply explore the source code, clone the KyuPy [repository](https://github.com/s-holst/kyupy) on GitHub. -Within your local checkout, run: -```commandline -pip3 install --user -e . -``` -to make the kyupy package available in your python environment. -The source code comes with tests that can be run with: -``` -pytest -``` - -KyuPy depends on the following packages: -* [lark-parser](https://pypi.org/project/lark-parser) -* [numpy](https://pypi.org/project/numpy) -* [numba](https://pypi.org/project/numba) (optional, required only for GPU/CUDA support) diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..7daa173 --- /dev/null +++ b/README.rst @@ -0,0 +1,28 @@ +KyuPy - Pythonic Processing of VLSI Circuits +============================================ + +KyuPy is a Python package for processing and analysis of non-hierarchical gate-level VLSI designs. +It contains fundamental building blocks for research software in the fields of VLSI test, diagnosis and reliability: + +* Efficient data structures for gate-level circuits and related design data. +* Partial `lark `_ parsers for common design files like + bench, gate-level verilog, standard delay format (SDF), standard test interface language (STIL). +* Bit-parallel gate-level 2-, 4-, and 8-valued logic simulation. +* GPU-accelerated high-throughput gate-level timing simulation. +* High-performance through the use of `numpy `_ and `numba `_. + + +Getting Started +--------------- + +KyuPy is available in `PyPI `_. +It requires Python 3.6 or newer, `lark-parser `_, and `numpy `_. +Although optional, `numba `_ should be installed for best performance. +GPU/CUDA support in numba may `require some additional setup `_. +If numba is not available, KyuPy will automatically fall back to slow, pure Python execution. + +The Jupyter Notebook `UsageExamples.ipynb `_ contains some useful examples to get familiar with the API. + +To work with the latest pre-release source code, clone the `KyuPy GitHub repository `_. +Run ``pip3 install --user -e .`` within your local checkout to make the package available in your Python environment. +The source code comes with tests that can be run with ``pytest``. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cb2e436 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,64 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +import sphinx_rtd_theme +sys.path.insert(0, os.path.abspath('../src')) + + + +# -- Project information ----------------------------------------------------- + +project = 'KyuPy' +copyright = '2020, Stefan Holst' +author = 'Stefan Holst' + +# The full version, including alpha/beta/rc tags +release = '0.0.2' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx_rtd_theme', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +# html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +autodoc_default_options = { + 'member-order': 'bysource', +} diff --git a/docs/datastructures.rst b/docs/datastructures.rst new file mode 100644 index 0000000..a66385c --- /dev/null +++ b/docs/datastructures.rst @@ -0,0 +1,30 @@ +Core Data Structures +==================== + +KyuPy provides two types of core data structures, one for gate-level circuits, and a few others for representing and storing logic data and signal values. +The data structures are designed to work together nicely with numpy arrays. +For example, all the nodes and connections in the circuit graph have numerical indices that can be used to access ndarrays with associated data. +Circuit graphs also define an ordering of inputs, outputs and other nodes to easily process test vector data and alike. + +Module :mod:`kyupy.circuit` +--------------------------- + +.. automodule:: kyupy.circuit + +.. autoclass:: kyupy.circuit.Node + :members: + +.. autoclass:: kyupy.circuit.Circuit + :members: + +Logic Values and Arrays +----------------------- + +.. automodule:: kyupy.logic + +.. autoclass:: kyupy.logic.MVArray + :members: + +.. autoclass:: kyupy.logic.BPArray + :members: + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..3caa343 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,12 @@ +.. include:: ../README.rst + +API Reference +------------- + +.. toctree:: + :maxdepth: 2 + + datastructures + parsers + simulators + diff --git a/docs/parsers.rst b/docs/parsers.rst new file mode 100644 index 0000000..4f7351f --- /dev/null +++ b/docs/parsers.rst @@ -0,0 +1,12 @@ +Parsers +======= + +bench + +verilog + +SDF + +STIL + + diff --git a/docs/simulators.rst b/docs/simulators.rst new file mode 100644 index 0000000..efee931 --- /dev/null +++ b/docs/simulators.rst @@ -0,0 +1,8 @@ +Simulators +========== + +Logic Sim + +Wave Sim + + diff --git a/setup.py b/setup.py index d56de0f..fb7aade 100644 --- a/setup.py +++ b/setup.py @@ -1,14 +1,13 @@ from setuptools import setup, find_packages -with open('README.md', 'r') as f: +with open('README.rst', 'r') as f: long_description = f.read() setup( name='kyupy', - version='0.0.1', + version='0.0.2', description='High-performance processing and analysis of non-hierarchical VLSI designs', long_description=long_description, - long_description_content_type='text/markdown', packages=find_packages(where='src'), package_dir={'': 'src'}, url='https://github.com/s-holst/kyupy', diff --git a/src/kyupy/circuit.py b/src/kyupy/circuit.py index bad9a67..605192c 100644 --- a/src/kyupy/circuit.py +++ b/src/kyupy/circuit.py @@ -1,3 +1,10 @@ +"""Data structures for representing non-hierarchical gate-level circuits. + +The class :class:`Circuit` is a container of nodes connected by lines. +A node is an instance of class :class:`Node`, +and a line is an instance of class :class:`Line`. +""" + from collections import deque @@ -19,36 +26,51 @@ class IndexList(list): class Node: - """A Node is a named entity in a circuit (e.g. a gate, a standard cell, - a named signal, or a fan-out point) that has connections to other nodes. - Each node contains: - - * `self.index`: a circuit-unique integer index. - * `self.kind`: a type describing its function (e.g. 'AND', 'NOR'). - The type '__fork__' is special. It signifies a named signal - or a fan-out in the circuit. Any other type is considered a physical cell. - * `self.name`: a name. Names must be unique among all forks and all cells - in the circuit. However, a fork (`self.kind=='__fork__'`) and a cell with - the same name may coexist. - * `self.ins`: a list of input connections (objects of class `Line`) - * `self.outs`: a list of output connections (objects of class `Line`). + """A named entity in a circuit (e.g. a gate, a standard cell, + a named signal, or a fan-out point) that is connected to other nodes via lines. + + The constructor automatically adds the new node to the given circuit. """ def __init__(self, circuit, name, kind='__fork__'): if kind == '__fork__': - if name in circuit.forks: - raise ValueError(f'fork of name {name} already exists.') + assert name not in circuit.forks, f'fork of name {name} already in circuit.' circuit.forks[name] = self else: - if name in circuit.cells: - raise ValueError(f'cell of name {name} already exists.') + assert name not in circuit.cells, f'cell of name {name} already in circuit.' circuit.cells[name] = self - self.index = len(circuit.nodes) circuit.nodes.append(self) self.circuit = circuit + """The :class:`Circuit` object the node is part of. + """ self.name = name + """The name of the node. + + Names must be unique among all forks and all cells in the circuit. + However, a fork (:code:`kind=='__fork__'`) and a cell with the same name may coexist. + """ self.kind = kind + """A string describing the type of the node. + + Common types are the names from a standard cell library or general gate names like 'AND' or 'NOR'. + If :code:`kind` is set to '__fork__', it receives special treatment. + A `fork` describes a named signal or a fan-out point in the circuit and not a physical `cell` like a gate. + In the circuit, the namespaces of forks and cells are kept separate. + While :code:`name` must be unique among all forks and all cells, a fork can have the same name as a cell. + The :code:`index`, however, is unique among all nodes; a fork cannot have the same index as a cell. + """ + self.index = len(circuit.nodes) - 1 + """A unique and consecutive integer index of the node within the circuit. + + It can be used to store additional data about the node :code:`n` + by allocating an array or list :code:`my_data` of length :code:`len(n.circuit.nodes)` and + accessing it by :code:`my_data[n.index]`. + """ self.ins = GrowingList() + """A list of input connections (:class:`Line` objects). + """ self.outs = GrowingList() + """A list of output connections (:class:`Line` objects). + """ def __repr__(self): ins = ' '.join([f'<{line.index}' if line is not None else '