Metadata-Version: 2.4
Name: pyrtl
Version: 1.0.3
Summary: RTL-level Hardware Design and Simulation Toolkit
Project-URL: Homepage, http://ucsbarchlab.github.io/PyRTL/
Project-URL: GitHub, https://github.com/UCSBarchlab/PyRTL
Project-URL: Documentation, https://pyrtl.readthedocs.io/
Project-URL: Changelog, https://github.com/UCSBarchlab/PyRTL/blob/development/CHANGELOG.md
Author: John Clow, UCSBarchlab
Author-email: Timothy Sherwood <sherwood@cs.ucsb.edu>
License: Copyright (c) 2015, Regents of the University of California
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of PyRTL nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Provides-Extra: blif
Requires-Dist: pyparsing; extra == 'blif'
Provides-Extra: svg
Requires-Dist: graphviz; extra == 'svg'
Description-Content-Type: text/markdown

<!-- This README is also published on PyPI. GitHub relative links, like
[link](docs/README.md) do not work on PyPI, so don't use them here. -->

PyRTL
=====

[![PyPI version](https://badge.fury.io/py/pyrtl.svg)](http://badge.fury.io/py/pyrtl)
[![Build Status](https://github.com/UCSBarchlab/PyRTL/actions/workflows/python-test.yml/badge.svg)](https://github.com/UCSBarchlab/PyRTL/actions/workflows/python-test.yml)
[![Code Coverage](https://codecov.io/github/UCSBarchlab/PyRTL/coverage.svg?branch=development)](https://codecov.io/github/UCSBarchlab/PyRTL?branch=development)
[![Documentation Status](https://readthedocs.org/projects/pyrtl/badge/?version=latest)](http://pyrtl.readthedocs.org/en/latest/?badge=latest)
[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/UCSBarchlab/PyRTL/development?filepath=%2Fipynb-examples%2F)

PyRTL provides a collection of classes for Pythonic [register-transfer
level](https://en.wikipedia.org/wiki/Register-transfer_level) design,
simulation, tracing, and testing suitable for teaching and research.
Simplicity, usability, clarity, and extensibility are overarching goals, rather
than performance or optimization. Features include:

* Elaboration-through-execution, meaning all of Python can be used including
  introspection.
* Design, instantiate, and simulate all in one file and without leaving Python.
* Export to, or import from, common HDLs (BLIF-in, Verilog-out currently
  supported).
* Examine execution with waveforms on the terminal or export to
  [`.vcd`](https://en.wikipedia.org/wiki/Value_change_dump) as projects scale.
* Elaboration, synthesis, and basic optimizations all included.
* Small and well-defined internal core structure means writing new transforms
  is easier.
* Batteries included means many useful components are already available.

What README would be complete without a screenshot? Below you can see the
waveform rendered right on the terminal for a [small state
machine](https://github.com/UCSBarchlab/PyRTL/blob/development/examples/example3-statemachine.py)
written in PyRTL.

![Command-line waveform for PyRTL state machine](https://github.com/UCSBarchlab/PyRTL/blob/development/docs/screenshots/pyrtl-statemachine.png?raw=true "PyRTL State Machine Screenshot")

### Tutorials and Documentation

* For users, more info and demo code is available on the [PyRTL project web
  page](http://ucsbarchlab.github.io/PyRTL/).
* Try the examples in the
  [`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples)
  directory. You can also [try the examples on
  MyBinder](https://mybinder.org/v2/gh/UCSBarchlab/PyRTL/development?filepath=%2Fipynb-examples%2F).
* [Full reference documentation](https://pyrtl.readthedocs.io/) is available.

### Package Contents

If you are just getting started with PyRTL, try starting with the
[`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples) to
get a sense of the "thinking with PyRTLs" required to design hardware in this
way. If you are looking for a deeper understanding, dive into the code for the
object [`Block`](https://pyrtl.readthedocs.io/en/latest/blocks.html#blocks). It
is the core data structure at the heart of PyRTL and defines its semantics at a
high level -- everything is converted to or from the small, simple set of
primitives defined there.

The package contains the following files and directories:
* [`pyrtl`](https://github.com/UCSBarchlab/PyRTL/tree/development/pyrtl)
  The module's source code.
* [`pyrtl/rtllib/`](https://github.com/UCSBarchlab/PyRTL/tree/development/pyrtl/rtllib)
  Finished PyRTL libraries which are hopefully both useful and documented.
* [`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples)
  A set of hardware design examples that show the main ideas behind PyRTL.
* [`tests`](https://github.com/UCSBarchlab/PyRTL/tree/development/tests)
  A set of unit tests for PyRTL which you can run with `pytest`.
* [`docs`](https://github.com/UCSBarchlab/PyRTL/tree/development/docs)
  Documentation written in
  [Sphinx](https://www.sphinx-doc.org/en/master/index.html)
  [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer).

### PyRTL Development Environment

All PyRTL developers should use the same tool versions to avoid confusing
situations where a test fails only on one person's computer, or the generated
documentation looks weird on another person's computer.

PyRTL uses [`uv`](https://docs.astral.sh/uv/) to ensure all developers work in
the same environment. `uv` manages the installation and versioning for all
other PyRTL developer tools, like `pytest` and `ruff`.

To set up a PyRTL development environment, you only need to install `uv`, by
following the [`uv` installation
instructions](https://docs.astral.sh/uv/getting-started/installation/).

After installing [`uv`](https://docs.astral.sh/uv/), you can run all the tests
with:

```shell
$ uv run just tests
```

And you can generate the Sphinx documentation with:

```shell
$ uv run just docs
```

`uv` will download and install Python and any required `pip` packages as
needed. `uv` caches installed software so future `uv` invocations will be fast.

### Contributing to PyRTL

*Picking a first project*

* One of the earliest things you should submit is a unit test that hits some
  [uncovered lines of code in
  PyRTL](https://codecov.io/github/UCSBarchlab/PyRTL?branch=development). For
  example, pick a `PyrtlError` that is not covered and add a unit test in
  [`tests`](https://github.com/UCSBarchlab/PyRTL/tree/development/tests)
  that will hit it.
* After you have that down check [PyRTL
  Issues](https://github.com/UCSBarchlab/PyRTL/issues) for a feature that is
  marked as "beginner friendly".
* Once you have that down, ask for access to the PyRTL-research repo where we
  keep experimental features and designs that could use more help!

*Coding style*

* All major functionality should have unit tests covering and documenting their
  use.
* All public functions and methods should have useful docstrings.
* All code needs to conform to
  [PEP8](https://www.python.org/dev/peps/pep-0008/) conventions.
* No new root-level dependencies on external libs, import locally if required
  for special functions.

*Workflow*

* [This Git tutorial](https://www.atlassian.com/git/tutorials/) is a useful
  reference for working with Git.
* [This blog
  post](http://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/)
  covers a useful Git Fork workflow for working on PyRTL.
* The `development` branch is the primary stable working branch (everyone is
  invited to submit pull requests).,
* Bugs and minor enhancements tracked directly through [GitHub
  Issues](https://github.com/UCSBarchlab/PyRTL/issues).
* When posting a bug please include a small code sample that triggers the bug,
  e.g. [Issue #56](https://github.com/UCSBarchlab/PyRTL/issues/56).
* When pushing a fix to a bug or enhancement please reference the Issue in the
  commit message, e.g. [Fix to Issue
  #56](https://github.com/UCSBarchlab/PyRTL/commit/1d5730db168a9e4490c580cb930075715468047a).
* Before sending a pull request, please run:

   ```shell
   $ uv run just presubmit
   ```

   to verify that all tests pass and that all documentation can be generated
   with your changes.

*Documentation*

* All important functionality should have an executable example in
  [`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples).

* All classes should have a [docstring](https://peps.python.org/pep-0257) that
  describes the class at a high level.

* All methods and functions should include a docstring in the following
  Sphinx-parsable format:
  ```python
  """One Line Summary (< 88 chars) of the function, followed by period.

  A longer description of what this function does and does not do. Describe any
  assumptions or invariants. Provide an example for user-facing functions.

  :param param1: Description of this parameter.
  :param param2: Longer parameter descriptions take up a newline with four
      leading spaces like this.

  :raises Exception: If this function raises an exception, explain when that
      occurs here.

  :return: Description of function's return value.
  """
  ```
* Sphinx parses [Python type
  annotations](https://docs.python.org/3/library/typing.html), so put type
  information into annotations instead of docstrings.
* The Sphinx-generated documentation is published to
  https://pyrtl.readthedocs.io/ .
* PyRTL's Sphinx build process is documented in
  [`docs/README.md`](https://github.com/UCSBarchlab/PyRTL/blob/development/docs/README.md).
* PyRTL's release process is documented in
  [`docs/release/README.md`](https://github.com/UCSBarchlab/PyRTL/blob/development/docs/release/README.md).

### Using PyRTL

We love to hear from users about their projects, and if there are issues we
will try our best to push fixes quickly. You can read more about how we have
been using it in our research at UCSB both in simulation and on FPGAs in [our
PyRTL paper at FPL](http://www.cs.ucsb.edu/~sherwood/pubs/FPL-17-pyrtl.pdf).

### Related Projects

It is always important to point out that PyRTL builds on the ideas of several
other related projects as we all share the common goal of trying to make
hardware design a better experience! You can read more about those
relationships on our [PyRTL project web
page](https://pyrtl.readthedocs.io/en/latest/#related-projects)
