diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 14b7c2d..e187043 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -24,10 +24,10 @@ jobs: with: python-version: "3.8" - name: Install Dependencies - run: make venv + run: make dependencies - name: Lint run: | - PATH=$PWD/venv/bin:$PATH make lint + make lint build: runs-on: ubuntu-22.04 @@ -45,16 +45,16 @@ jobs: with: python-version: ${{ matrix.python-version }} - name: Install Dependencies - run: make venv + run: make dependencies - name: Build Package run: | - PATH=$PWD/venv/bin:$PATH make build + make build - name: Install Package run: | - PATH=$PWD/venv/bin:$PATH make install + make install - name: Run CACE run: | - PATH=$PWD/venv/bin:$PATH cace -help + cace -help docs: runs-on: ubuntu-22.04 @@ -68,13 +68,7 @@ jobs: with: python-version: 3.8 - name: Install Dependencies - run: make venv - - name: Build Package - run: | - PATH=$PWD/venv/bin:$PATH make build - - name: Install Package - run: | - PATH=$PWD/venv/bin:$PATH make install + run: make dependencies - name: Build Documentation run: | make docs diff --git a/Makefile b/Makefile index d1435fb..fa50617 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ -.PHONY: init -init: +.PHONY: dependencies +dependencies: pip3 install -r requirements.txt pip3 install -r requirements_dev.txt pip3 install -r requirements_docs.txt @@ -32,24 +32,13 @@ editable: upload: python3 -m twine upload --repository pypi dist/* -venv: venv/manifest.txt -venv/manifest.txt: ./requirements_docs.txt ./requirements_dev.txt ./requirements.txt - rm -rf venv - python3 -m venv ./venv - PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade pip - PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade -r ./requirements_docs.txt - PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade -r ./requirements_dev.txt - PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade -r ./requirements.txt - PYTHONPATH= ./venv/bin/python3 -m pip freeze > $@ - @echo ">> Venv prepared." - .PHONY: docs -docs: venv - . venv/bin/activate; $(MAKE) -C docs html +docs: + $(MAKE) -C docs html .PHONY: host-docs -host-docs: venv - . venv/bin/activate; python3 -m http.server --directory ./docs/build/html +host-docs: + python3 -m http.server --directory ./docs/build/html .PHONY: clean clean: diff --git a/README.md b/README.md index 35da50c..239cd5e 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@

Circuit Automatic Characterization Engine

License: Apache 2.0 + GitHub Actions Status Badge + Documentation Build Status Badge Python 3.8 or higher Code Style: blue

@@ -41,23 +43,20 @@ Or to start the GUI: $ cace-gui ``` +Information on how to use CACE can be found in the documentation at [cace.readthedocs.io](https://cace.readthedocs.io/). + ## Development ### Dependencies -To install the dependencies for CACE, run: - - $ pip3 install -r requirements.txt +> [!IMPORTANT] +> You may need to set up a Python [virtual environment](https://docs.python.org/3/library/venv.html). -To install the dependencies to build CACE, run: - - $ pip3 install -r requirements_dev.txt - -To install the dependencies to build the documentation for CACE, run: +To install the dependencies for CACE, run: - $ pip3 install -r requirements_docs.txt + $ make dependencies -### CACE +### Python Package To build the Python package, run: @@ -77,10 +76,26 @@ To install the package in editable mode, run: $ make editable ``` +### Documentation + +To build the documentation, run: + +``` +$ make docs +``` + +To host the docs, run: + +``` +make host-docs +``` + +> [!NOTE] +> The documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). ## CACE GUI syntax - /path/to/cace_gui.py [path/to/project.txt] + $ cace-gui [path/to/project.txt] where optional file project.txt (normally .txt where is the name of the circuit to be @@ -103,7 +118,7 @@ $ make editable ## CACE command line syntax - /path/to/cace.py [options] + $ cace [options] where is a format 4.0 ASCII CACE file and is the name of the file to write. @@ -154,33 +169,22 @@ $ make editable The following repositories contain example circuit designs, each having a "cace/" subdirectory with a specification input file in the format described below, and a set of testbench schematics which are used by CACE to measure all specified electrical and physical parameters, generate results, and analyze them to determine circuit performance over corners. -(NOTE: Example repositories, like CACE itself, are currently a work in progress.) +> [!NOTE] +> Example repositories, like CACE itself, are currently a work in progress. All repositories are rooted at: [https://github.com/RTimothyEdwards/](https://github.com/RTimothyEdwards/). Example circuit repositories: - sky130_ef_ip__instramp Instrumentation amplifier - sky130_ef_ip__rdac3v_8bit 8-bit resistor ladder DAC - sky130_ef_ip__samplehold sample-and-hold circuit - sky130_ef_ip__driveramp Rail-to-rail driver amplifier - sky130_ef_ip__ccomp3v Rail-to-rail continuous comparator - sky130_ef_ip__rc_osc_500k R-C oscillator, 500kHz nominal output - sky130_ef_ip__xtal_osc_16M Crystal oscillator, 4 to 15MHz - sky130_ef_ip__xtal_osc_32k Crystal oscillator, 32kHz +- [sky130_ef_ip__instramp](https://github.com/RTimothyEdwards/sky130_ef_ip__instramp) Instrumentation amplifier +- [sky130_ef_ip__rdac3v_8bit](https://github.com/RTimothyEdwards/sky130_ef_ip__rdac3v_8bit) 8-bit resistor ladder DAC +- sky130_ef_ip__samplehold sample-and-hold circuit +- sky130_ef_ip__driveramp Rail-to-rail driver amplifier +- sky130_ef_ip__ccomp3v Rail-to-rail continuous comparator +- sky130_ef_ip__rc_osc_500k R-C oscillator, 500kHz nominal output +- sky130_ef_ip__xtal_osc_16M Crystal oscillator, 4 to 15MHz +- sky130_ef_ip__xtal_osc_32k Crystal oscillator, 32kHz Each of these repositories contains a circuit designed with the SkyWater sky130 process open PDK, and contains schematics, layout, and CACE characterization. NOTE: These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE. - -## Documentation - -To build the documentation, run: - - $ make docs - -Th host the docs, run: - - $ make host-docs - -Note: The documentation is not yet hosted online anywhere. diff --git a/docs/source/index.rst b/docs/source/index.rst index 2869783..6248dc2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,8 @@ Welcome to CACE's documentation! ================================ +Please note that this documentation is still a work in progress. + .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/docs/source/usage/getting_started.md b/docs/source/usage/getting_started.md index f1ac649..d8c2566 100644 --- a/docs/source/usage/getting_started.md +++ b/docs/source/usage/getting_started.md @@ -2,9 +2,49 @@ ## Installation -For now, CACE can be manually installed using pip. +You'll need the following: -First the Python package needs to be build: +- Python 3.8 or higher with PIP and Tkinter + +CACE can be installed directly from PyPI: + + $ python3 -m pip install --upgrade cace +Prerequisite design tools: + +- xschem: [https://github.com/stefanschippers/xschem](https://github.com/stefanschippers/xschem) +- ngspice: git://git.code.sf.net/p/ngspice/ngspice +- magic: [https://github.com/RTimothyEdwards/magic](https://github.com/RTimothyEdwards/magic) + +## Usage + +If installed as Python package, CACE can be started from the command line using: + +``` +$ cace +``` + +Or to start the GUI: + +``` +$ cace-gui +``` + +Information on how to use CACE can be found in the documentation at [cace.readthedocs.io](https://cace.readthedocs.io/). + +## Development + +### Dependencies + +> [!IMPORTANT] +> You may need to set up a Python [virtual environment](https://docs.python.org/3/library/venv.html). + +To install the dependencies for CACE, run: + + $ make dependencies + +### Python Package + +To build the Python package, run: ``` $ make build @@ -16,33 +56,32 @@ To install the package, run: $ make install ``` -CACE is currently a work in progress and does not have an -installer; it may be run directly from the source repository -clone. Future work will allow CACE to be installed with the -standard python "pip" installer or a Makefile install target, -and run from the command line simply as "cace". +To install the package in editable mode, run: -## Usage +``` +$ make editable +``` + +### Documentation -If installed properly as Python package, CACE can be started from the command line using: +To build the documentation, run: ``` -$ cace +$ make docs ``` -Or to start the GUI: +To host the docs, run: ``` -$ cace-gui +make host-docs ``` +> [!NOTE] +> The documentation can be viewed online at [cace.readthedocs.io](https://cace.readthedocs.io/). -The `cace_gui.py` script is a top-level GUI for the CACE system. The CACE system can also be run manually as `cace_cli.py`. For -interactive usage information for the command line, run `cace-cli.py` without any arguments. - -CACE GUI syntax: +## CACE GUI syntax - /path/to/cace_gui.py [path/to/project.txt] + $ cace-gui [path/to/project.txt] where optional file project.txt (normally .txt where is the name of the circuit to be @@ -63,9 +102,9 @@ CACE GUI syntax: standalone circuits, or a project may simply be a collection of circuits (library) without a specific single top level. -CACE command line syntax: +## CACE command line syntax - /path/to/cace.py [options] + $ cace [options] where is a format 4.0 ASCII CACE file and is the name of the file to write. @@ -110,4 +149,27 @@ CACE command line syntax: Option "-nosim" does not re-run simulations if the output file exists. (Warning---does not check if simulations are out of date). - Option "-summary" prints a summary of results at the end. \ No newline at end of file + Option "-summary" prints a summary of results at the end. + +## Examples + +The following repositories contain example circuit designs, each having a "cace/" subdirectory with a specification input file in the format described below, and a set of testbench schematics which are used by CACE to measure all specified electrical and physical parameters, generate results, and analyze them to determine circuit performance over corners. + +(NOTE: Example repositories, like CACE itself, are currently a work in progress.) + +All repositories are rooted at: [https://github.com/RTimothyEdwards/](https://github.com/RTimothyEdwards/). + +Example circuit repositories: + +- [sky130_ef_ip__instramp](https://github.com/RTimothyEdwards/sky130_ef_ip__instramp) Instrumentation amplifier +- [sky130_ef_ip__rdac3v_8bit](https://github.com/RTimothyEdwards/sky130_ef_ip__rdac3v_8bit) 8-bit resistor ladder DAC +- sky130_ef_ip__samplehold sample-and-hold circuit +- sky130_ef_ip__driveramp Rail-to-rail driver amplifier +- sky130_ef_ip__ccomp3v Rail-to-rail continuous comparator +- sky130_ef_ip__rc_osc_500k R-C oscillator, 500kHz nominal output +- sky130_ef_ip__xtal_osc_16M Crystal oscillator, 4 to 15MHz +- sky130_ef_ip__xtal_osc_32k Crystal oscillator, 32kHz + +Each of these repositories contains a circuit designed with the SkyWater sky130 process open PDK, and contains schematics, layout, and CACE characterization. + +NOTE: These repositories are a work in progress, and may not exist yet or may not have a characterization setup for CACE.