Skip to content

Commit ec801df

Browse files
milanofthemilanofthe
committed
Add PathSim toolbox template scaffold
0 parents  commit ec801df

14 files changed

Lines changed: 998 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [master, main]
6+
pull_request:
7+
8+
jobs:
9+
lint:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- uses: actions/setup-python@v5
15+
with:
16+
python-version: "3.13"
17+
18+
- name: Install ruff
19+
run: pip install ruff
20+
21+
- name: ruff check
22+
run: ruff check src/ tests/
23+
24+
- name: ruff format
25+
run: ruff format --check src/ tests/
26+
27+
test:
28+
runs-on: ubuntu-latest
29+
strategy:
30+
matrix:
31+
python-version: ["3.10", "3.11", "3.12", "3.13"]
32+
33+
steps:
34+
- uses: actions/checkout@v4
35+
with:
36+
fetch-depth: 0 # full history so setuptools-scm can derive the version
37+
38+
- uses: actions/setup-python@v5
39+
with:
40+
python-version: ${{ matrix.python-version }}
41+
42+
- name: Install
43+
run: pip install -e ".[test]" mypy
44+
45+
- name: mypy
46+
run: mypy src/pathsim_toolbox
47+
48+
- name: pytest
49+
run: pytest tests/ -v --tb=short

‎.github/workflows/publish.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
id-token: write # trusted publishing — no API token needed
11+
12+
jobs:
13+
publish:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0 # full history so setuptools-scm derives the release version
19+
20+
- uses: actions/setup-python@v5
21+
with:
22+
python-version: "3.x"
23+
24+
- name: Build package
25+
run: |
26+
pip install build
27+
python -m build
28+
29+
- name: Publish package
30+
uses: pypa/gh-action-pypi-publish@release/v1

‎.gitignore‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Notebooks (except documentation notebooks)
10+
*.ipynb
11+
!docs/**/*.ipynb
12+
13+
# Distribution / packaging
14+
.Python
15+
build/
16+
develop-eggs/
17+
dist/
18+
downloads/
19+
eggs/
20+
.eggs/
21+
lib/
22+
lib64/
23+
parts/
24+
sdist/
25+
var/
26+
wheels/
27+
*.egg-info/
28+
.installed.cfg
29+
*.egg
30+
*.pypirc
31+
32+
# Installer logs
33+
pip-log.txt
34+
pip-delete-this-directory.txt
35+
36+
# Unit test / coverage reports
37+
htmlcov/
38+
.tox/
39+
.coverage
40+
.coverage.*
41+
.cache
42+
nosetests.xml
43+
coverage.xml
44+
*.cover
45+
.hypothesis/
46+
test_reports/
47+
*.pyc
48+
.pytest_cache/
49+
.mypy_cache/
50+
.ruff_cache/
51+
52+
# Jupyter Notebook
53+
.ipynb_checkpoints
54+
55+
# pyenv
56+
.python-version
57+
58+
# Environment
59+
.env
60+
.venv
61+
env/
62+
venv/
63+
ENV/
64+
65+
# Shell
66+
*.bat
67+
68+
# IDEs
69+
.vscode/
70+
.idea/
71+
72+
# OS generated files
73+
.DS_Store
74+
.DS_Store?
75+
._*
76+
.Spotlight-V100
77+
.Trashes
78+
ehthumbs.db
79+
Thumbs.db
80+
81+
# Claude
82+
.claude
83+
84+
# setuptools-scm generated version file
85+
_version.py

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 PathSim
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<!-- TEMPLATE:START -->
2+
> **This is the PathSim toolbox template.**
3+
> The README below still contains placeholders. To turn this template into a
4+
> real toolbox, create a repository from it, then run the initializer:
5+
>
6+
> ```bash
7+
> python init.py <name> --description "<one-line description>" --label <Label>
8+
> ```
9+
>
10+
> It renames the package, rewrites every reference, and removes this banner.
11+
> See [`TEMPLATE.md`](TEMPLATE.md) for the full setup, including registering
12+
> the toolbox with the documentation build.
13+
14+
---
15+
<!-- TEMPLATE:END -->
16+
17+
<p align="center">
18+
<strong>A toolbox for PathSim</strong>
19+
</p>
20+
21+
<p align="center">
22+
<a href="https://pypi.org/project/pathsim-toolbox/"><img src="https://img.shields.io/pypi/v/pathsim-toolbox" alt="PyPI"></a>
23+
<img src="https://img.shields.io/github/license/pathsim/pathsim-toolbox" alt="License">
24+
</p>
25+
26+
<p align="center">
27+
<a href="https://pathsim.org">Homepage</a> &bull;
28+
<a href="https://docs.pathsim.org/toolbox">Documentation</a> &bull;
29+
<a href="https://github.com/pathsim/pathsim-toolbox">GitHub</a>
30+
</p>
31+
32+
---
33+
34+
PathSim-Toolbox extends the [PathSim](https://github.com/pathsim/pathsim)
35+
simulation framework with specialized blocks. All blocks follow the standard
36+
PathSim block interface and can be connected into simulation diagrams.
37+
38+
## Blocks
39+
40+
| Block | Description | Key Parameters |
41+
|-------|-------------|----------------|
42+
| `FirstOrderLag` | First-order lag / low-pass filter | `tau`, `y0` |
43+
44+
## Install
45+
46+
```bash
47+
pip install pathsim-toolbox
48+
```
49+
50+
## Quick Example
51+
52+
```python
53+
from pathsim import Simulation, Connection
54+
from pathsim.blocks import Source, Scope
55+
from pathsim_toolbox import FirstOrderLag
56+
57+
src = Source(lambda t: float(t > 1)) # unit step at t = 1
58+
lag = FirstOrderLag(tau=2.0) # first-order lag
59+
sco = Scope(labels=["input", "output"])
60+
61+
sim = Simulation(
62+
blocks=[src, lag, sco],
63+
connections=[
64+
Connection(src, lag[0], sco[0]),
65+
Connection(lag, sco[1]),
66+
],
67+
dt=0.01,
68+
)
69+
sim.run(20)
70+
sco.plot()
71+
```
72+
73+
## Development
74+
75+
```bash
76+
pip install -e ".[test]" ruff mypy
77+
ruff check src/ tests/ # lint
78+
ruff format src/ tests/ # format
79+
mypy src/pathsim_toolbox # type check
80+
pytest tests/ -v # run tests
81+
```
82+
83+
## License
84+
85+
MIT

‎TEMPLATE.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Using this template
2+
3+
This repository is a **GitHub template** for new PathSim toolboxes. It gives
4+
every toolbox the same layout, CI, packaging and docs contract, so they don't
5+
drift apart.
6+
7+
> This file is for the person setting up a new toolbox. The `init.py` script
8+
> deletes it once initialization is done.
9+
10+
## 1. Create the repo
11+
12+
On GitHub, click **Use this template → Create a new repository**. Name it
13+
`pathsim-<name>` and put it in the `pathsim` organization.
14+
15+
## 2. Run the initializer
16+
17+
Clone the new repo and run:
18+
19+
```bash
20+
python init.py <name> --description "<one-line description>" --label <Label>
21+
```
22+
23+
- `<name>` — short, lowercase, e.g. `rf`, `chem`, `vehicle`. Becomes the
24+
package `pathsim_<name>`, the distribution `pathsim-<name>`, and the docs
25+
slug `docs.pathsim.org/<name>`.
26+
- `--description` — one-line project description for `pyproject.toml` / README.
27+
- `--label` — display capitalization for `PathSim-<Label>` (defaults to the
28+
capitalized name; pass `RF` explicitly for acronyms).
29+
30+
The script renames `src/pathsim_toolbox/`, rewrites every reference across the
31+
repo, removes the template banner from `README.md`, and finally deletes
32+
`TEMPLATE.md` and `init.py`. Commit the result.
33+
34+
## 3. Replace the placeholder content
35+
36+
- `src/pathsim_<name>/example_block.py` — replace `FirstOrderLag` with your
37+
real blocks. Keep the structure: header comment, docstring documenting
38+
math / parameters / ports, input validation, `*_port_labels`.
39+
- `tests/` — mirror the structure of `src/`. Tests run with both `unittest`
40+
and `pytest`; physics is verified through a full `Simulation`.
41+
- `docs/source/examples/` — example notebooks. The placeholder is a copied
42+
PathSim core example; replace it with notebooks that demonstrate your
43+
blocks. Every `*.ipynb` here is executed and rendered by the docs build.
44+
45+
## 4. Register with the docs build
46+
47+
The documentation site (`docs.pathsim.org`) is built by the
48+
[`pathsim/docs`](https://github.com/pathsim/docs) repository. It clones every
49+
toolbox listed in `scripts/lib/config.py` and builds API docs + notebooks per
50+
git tag.
51+
52+
To make the new toolbox appear, open a PR on `pathsim/docs` adding an entry to
53+
`PACKAGES` and `MIN_SUPPORTED_VERSIONS` in `scripts/lib/config.py`:
54+
55+
```python
56+
"<name>": {
57+
"repo": ROOT_DIR / "pathsim-<name>",
58+
"source": ROOT_DIR / "pathsim-<name>" / "src",
59+
"notebooks": ROOT_DIR / "pathsim-<name>" / "docs" / "source" / "examples",
60+
"figures": ROOT_DIR / "pathsim-<name>" / "docs" / "source" / "examples" / "figures",
61+
"display_name": "PathSim-<Label>",
62+
"griffe_package": "pathsim_<name>",
63+
"github_repo": "pathsim/pathsim-<name>",
64+
"root_modules": ["pathsim_<name>"],
65+
"required": False,
66+
},
67+
```
68+
69+
The repo-side docs contract is just: an importable package under `src/` and
70+
`*.ipynb` files under `docs/source/examples/`. No Sphinx — the docs build owns
71+
all rendering.
72+
73+
## 5. Releasing
74+
75+
`.github/workflows/publish.yml` publishes to PyPI via trusted publishing when
76+
a GitHub Release is published. Versions come from git tags via `setuptools-scm`,
77+
so tag releases as `vX.Y.Z`. Configure a
78+
[PyPI trusted publisher](https://docs.pypi.org/trusted-publishers/) for the
79+
project pointing at this repo and the `publish.yml` workflow.

0 commit comments

Comments
 (0)