Merge pull request #1 from geddy11/update

chore: transfer files from temporary project

.github/workflows/ci-cd.yml

@@ -10,29 +10,43 @@ jobs:
     # Define job steps
     steps:
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
 
       - name: Check-out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install poetry
         uses: snok/install-poetry@v1
 
       - name: Install package
         run: poetry install
 
+      - name: Linter
+        uses: psf/black@stable
+
       - name: Test with pytest
         run: poetry run pytest tests/ --cov=sysloss --cov-report=xml
 
       - name: Use Codecov to track coverage
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4.0.1
         with:
-          files: ./coverage.xml   # coverage report
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: geddy11/sysloss
+          #files: ./coverage.xml   # coverage report (dont enable)
+
+      # - name: Coverage badge
+      #   uses: tj-actions/coverage-badge-py@v2
+
+      - name: Install  Jupyter-book
+        run: pip install jupyter-book==1.0.0 sphinx-autoapi matplotlib toml scipy rich rustworkx pandas numpy
+
+      - name: Create Sphinx configuration
+        run: jupyter-book config sphinx docs
 
       - name: Build documentation
-        run: poetry run make html --directory docs/
+        run: sphinx-build docs docs/_build/html -b html
 
   cd:
     permissions:
@@ -51,12 +65,12 @@ jobs:
     # Define job steps
     steps:
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
 
       - name: Check-out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -92,3 +106,5 @@ jobs:
         if: steps.release.outputs.released == 'true'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+
+

.gitignore

@@ -1,3 +1,7 @@
+*.json
+!tests/data/*.json
+work
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -70,6 +74,9 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/jupyter_execute
+docs/conf.py
+docs/nb/*.toml
 
 # PyBuilder
 target/
@@ -140,6 +147,3 @@ dmypy.json
 
 # MacOS
 .DS_Store
-
-# Various
-work

.readthedocs.yml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
   jobs:
     post_create_environment:
       # Install poetry
@@ -20,7 +20,10 @@ build:
     post_install:
       # Install dependencies with 'docs' dependency group
       # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
-      - poetry install
+      - poetry install --with docs
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      - "jupyter-book config sphinx docs/"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

CHANGELOG.md

@@ -1,7 +1,2 @@
 # Changelog
 
-<!--next-version-placeholder-->
-
-## v0.1.0 (29/02/2024)
-
-- First release of `sysloss`!

CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+title: sysLoss
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Geir
+    family-names: Drange
+    affiliation: Inventas AS
+    orcid: 'https://orcid.org/0009-0009-6795-8583'
+repository-code: 'https://github.com/geddy11/sysloss'
+url: 'https://github.com/geddy11/sysloss'
+abstract: sysLoss is a tool for analyzing system power and losses.
+keywords:
+  - system
+  - power
+  - loss
+license: MIT
+version: 1.0.0

CONTRIBUTING.md

@@ -63,9 +63,11 @@ Ready to contribute? Here's how to set up `sysloss` for local development.
 
 Before you submit a pull request, check that it meets these guidelines:
 
-1. The pull request should include additional tests if appropriate.
-2. If the pull request adds functionality, the docs should be updated.
-3. The pull request should work for all currently supported operating systems and versions of Python.
+1. Use Black code formatter (formatting is checked in the CI pipeline).
+2. The pull request should include additional tests if appropriate. Code coverage shall be 100%.
+3. If the pull request adds functionality, the docs shall be updated.
+4. The pull request should work for all currently supported operating systems and versions of Python.
+5. Tutorials shall not contain references to or mentions of specific vendors, products or components.
 
 ## Code of Conduct
 

README.md

@@ -1,16 +1,47 @@
-# sysloss
 
-Power analysis of circuits and systems.
+![sysLoss logo](docs/sysloss.svg)
 
-## Installation
+<p align="center">
+<a href="https://github.com/geddy11/tmp_sl/actions"><img alt="Actions Status" src="https://github.com/geddy11/tmp_sl/actions/workflows/ci-cd.yml/badge.svg"></a>
+<a><img alt="PyPI" src="https://img.shields.io/pypi/v/sysloss"></a>
+<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+<a href="https://www.conventionalcommits.org"><img alt="Conv. commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white"></a>
+</p>
+
+# sysLoss
+sysLoss is a tool for analyzing system power and losses. From the smallest IoT sensor to large industrial installations. The tool is efficient and easy to use, the analysis result provides a detailed report on voltages, currents, power and efficiency for every component defined in the system. Output format is Pandas DataFrame: Create charts, plots and export to Excel and other formats. 
 
+## Installation
 ```bash
 $ pip install sysloss
 ```
 
 ## Usage
-
-- TODO
+```python
+from sysloss.components import *
+from sysloss.system import System
+
+bts = System("Bluetooth sensor", Source("CR2032", vo=3.0, rs=10))
+bts.add_comp("CR2032", comp=Converter("Buck 1.8V", vo=1.8, eff=0.87))
+bts.add_comp("Buck 1.8V", comp=PLoad("MCU", pwr=13e-3))
+bts.add_comp("CR2032", comp=Converter("Boost 5V", vo=5.0, eff=0.82))
+bts.add_comp("Boost 5V", comp=RLoss("RC filter", rs=6.8))
+bts.add_comp("RC filter", comp=ILoad("Sensor", ii=6e-3))
+bts.tree()
+```
+```
+Bluetooth sensor
+└── CR2032
+    ├── Boost 5V
+    │   └── RC filter
+    │       └── Sensor
+    └── Buck 1.8V
+        └── MCU
+```
+```python
+bts.solve()
+```
+![result](docs/bts.png)
 
 ## Contributing
 
@@ -19,7 +50,3 @@ Interested in contributing? Check out the contributing guidelines. Please note t
 ## License
 
 `sysloss` was created by Geir Drange. It is licensed under the terms of the MIT license.
-
-## Credits
-
-`sysloss` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).

docs/Getting started.md

@@ -0,0 +1,47 @@
+# Welcome to sysLoss
+*sysLoss* is a tool for analyzing system power and losses. From the smallest IoT sensor to large industrial installations. The tool is efficient and easy to use, the analysis result provides a detailed report on voltages, currents, power and efficiency for every component defined in the system. Output format is Pandas DataFrame: Create charts, plots and export to Excel and other formats. 
+
+## Installation
+To get started with *sysLoss*, install the python package from PyPI with:
+```bash
+$ pip install sysloss
+```
+Upgrade to the latest release with:
+```bash
+$ pip install --upgrade sysloss
+```
+
+## First system model
+A simple, battery-powered Bluetooth sensor can be defined as simple as this:
+```python
+from sysloss.components import *
+from sysloss.system import System
+
+bts = System("Bluetooth sensor", Source("CR2032", vo=3.0, rs=10))
+bts.add_comp("CR2032", comp=Converter("Buck 1.8V", vo=1.8, eff=0.87))
+bts.add_comp("Buck 1.8V", comp=PLoad("MCU", pwr=13e-3))
+bts.add_comp("CR2032", comp=Converter("Boost 5V", vo=5.0, eff=0.82))
+bts.add_comp("Boost 5V", comp=RLoss("RC filter", rs=6.8))
+bts.add_comp("RC filter", comp=ILoad("Sensor", ii=6e-3))
+bts.tree()
+```
+```
+Bluetooth sensor
+└── CR2032
+    ├── Boost 5V
+    │   └── RC filter
+    │       └── Sensor
+    └── Buck 1.8V
+        └── MCU
+```
+```python
+bts.solve()
+```
+![result](bts.png)
+
+## Next step
+The best way to learn *sysLoss* is to explore the tutorials section. The tutorials are Jupyter Notebooks that can also be found in the GitHub repository under docs/nb.
+
+```{tableofcontents}
+```
+

docs/_config.yml

@@ -34,4 +34,24 @@ repository:
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
 html:
   use_issues_button: true
-  use_repository_button: true
+  use_repository_button: true
+
+# Sphinx autodoc
+sphinx:
+  extra_extensions:
+    - 'autoapi.extension'
+#    - 'sphinx.ext.autodoc'
+    - 'sphinx.ext.napoleon'
+    - 'sphinx.ext.viewcode'
+#    - 'sphinx_external_toc'
+#    - 'sphinx.ext.autosummary'
+  config:
+#    autosummary_generate: True
+
+  config:
+    autoapi_dirs: ["../src"]  # location to parse for API reference
+    autoapi_options: 
+      ['members', 'undoc-members']
+    #external_toc_path: "docs/_toc.yml"
+    #html_theme: "sphinx_rtd_theme"
+    add_module_names: False

docs/_toc.yml

@@ -2,8 +2,13 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: intro
+root: Getting started
 chapters:
-- file: markdown
-- file: notebooks
-- file: markdown-notebooks
+- file: autoapi/index
+- file: nb/Component files
+- file: tutorials
+  sections:
+  - file: nb/Bluetooth sensor
+  - file: nb/Sensor daisy chain
+  - file: nb/PCIe FPGA
+  - file: nb/Datacenter rack