Skip to content

Commit 3901bd9

Browse files
HugoMValeHugoMVale
authored
Refactor equations of state, enhance documentation, and add emulsion features (#2)
* Update project description * Rename alpha to beta and beta to kappa * Add GasEoS documentation * Enhance equations of state with thermal expansion and compressibility methods * Remove unnecessary pass statements from abstract methods in EoS and GasEoS classes * Replace alpha method calls with kappa in Tait examples * Fix typo in docstring for hessian_forward function * Clarify mathematical definitions for thermal expansion and compressibility coefficients in Tait class * rename MolecularACM; add base method for gamma. * Refactor docstrings to use "Calculate" instead of "Compute" * Refactor docstrings to use "Calculate" for consistency and clarity * Refactor equations of state classes to improve docstring clarity and consistency; add base methods for gas EoS calculations. * Add typing_extensions for compatibility with Python < 3.12; refactor imports for consistency * Fix kwarg error * add aR * Improve docstring clarity for CubicEoS * add pre-commit; fix black typo * Add agent guide for consistent development practices * Add VSCode configuration files and update .gitignore * add nbar_Ugelstad_Mork * update sep * mkdocs<2.0 * improve nbar_Stockmayer_OToole * mark test_Cubic_departures as expected failure due to incomplete implementation * add unfixable rule for F401 in ruff configuration * update VSCode settings * fix: specify engine in read_csv * refactor: enhance type alias documentation and organization in types.py * feat: introduce physical constants module and refactor imports across the codebase * feat: introduce physical constants module and refactor imports across the codebase * feat: add nbar_Ugelstad function and update related documentation and tests * feat: add desorption functions and corresponding tests for K0_Nomura and kdesorption_Asua * feat: add keyword-only arguments for tolerance and maximum iterations in nbar_Ugelstad function * fix g * switch from black to ruff * rename module types to typing * add benchmarks * refactor: add slots=True to dataclass definitions for memory optimization * fix: update test_K0_Nomura parameters and expected value for accuracy * style: format __all__ declaration for consistency * style: capitalize notes and references in docstrings for consistency * add to_html function for generating Base64-encoded Matplotlib figures in HTML * fix: correct import path for FloatArray in base.py * fix: update import statements for consistency and clarity * rename module types to typing * fix types and missing import in example * add n2bar, compartmentalization_factor * add kentry_diffusion_reversible * polish docstrings * update doc of entry methods * fix: correct exclusion for Python 3.12 in CI matrix * add ref * fix: rename Types to Typing in navigation * fix: rename FlashResult to Flash2Result * add K_Wilson function and documentation * refactor check_shape * add check_shape * fix: update parameter description for model instances in IdealSolution, NRTL, UNIQUAC, and Wilson classes * implement ScatchardHildebrand model * implement ScatchardHildebrand model * add ScatchardHildebrand * update tutorials * move button up * add eos tutorial * format imports
1 parent 042c653 commit 3901bd9

132 files changed

Lines changed: 3383 additions & 898 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/test.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@ jobs:
1212
resolution: ["lowest-direct", "highest"]
1313
python-version: ["3.10", "3.11", "3.12", "3.13"]
1414
exclude:
15+
- python-version: "3.12"
16+
resolution: "lowest-direct"
1517
- python-version: "3.13"
1618
resolution: "lowest-direct" #numba 0.60 requires python < 3.13
17-
1819
steps:
1920
- name: Checkout code
2021
uses: actions/checkout@v4

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22

33
biblio
44
notes.md
5-
.vscode
65
.python-version
76
uv.lock
87

‎.pre-commit-config.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# See https://pre-commit.com for more information
2+
# This repo uses local hooks so formatting/linting runs via the pinned `uv.lock`.
3+
4+
default_language_version:
5+
python: python3
6+
7+
repos:
8+
- repo: local
9+
hooks:
10+
- id: ruff
11+
name: ruff (lint)
12+
entry: uv run --frozen ruff check
13+
language: system
14+
types: [python]
15+
16+
- id: ruff-format
17+
name: ruff (format)
18+
entry: uv run --frozen ruff format
19+
language: system
20+
types: [python]

‎.vscode/extensions.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"recommendations": [
3+
"ms-python.python",
4+
"charliermarsh.ruff"
5+
]
6+
}

‎.vscode/launch.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
// Use IntelliSense to learn about possible attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"name": "Python: Current File",
9+
"type": "debugpy",
10+
"request": "launch",
11+
"program": "${file}",
12+
"console": "integratedTerminal",
13+
"justMyCode": true
14+
}
15+
]
16+
}

‎.vscode/settings.json‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,23 @@
11
{
2-
"python.testing.pytestArgs": [
3-
"tests"
2+
"ruff.path": [
3+
"uv",
4+
"run",
5+
"--frozen",
6+
"ruff"
47
],
58
"python.testing.unittestEnabled": false,
6-
"python.testing.pytestEnabled": true
9+
"python.testing.pytestEnabled": true,
10+
"[python]": {
11+
"editor.rulers": [
12+
90
13+
],
14+
"editor.formatOnSave": true,
15+
"editor.defaultFormatter": "charliermarsh.ruff",
16+
"editor.codeActionsOnSave": {
17+
"source.fixAll": "explicit",
18+
"source.fixAll.ruff": "explicit",
19+
"source.organizeImports": "never",
20+
"source.organizeImports.ruff": "never"
21+
}
22+
}
723
}

‎AGENTS.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Agent guide (PolyKin)
2+
3+
This repository is a Python package (src-layout) built and tested via `uv`.
4+
This document is written for automated coding agents and human maintainers who want
5+
consistent, low-friction changes.
6+
7+
## Ground rules
8+
9+
- Keep changes minimal and scoped to the user request.
10+
- Prefer repo-standard tooling and commands (see below) so CI matches local runs.
11+
- Do not change `README.md` unless explicitly requested.
12+
- Avoid editing generated content under `docs/generated/`.
13+
- When making behavioral changes, add or update tests under `tests/`.
14+
15+
## Repo layout
16+
17+
- Source: `src/polykin/`
18+
- Tests: `tests/` (mirrors package subdomains like `thermo/`, `kinetics/`, etc.)
19+
- Docs (MkDocs Material): `docs/` (includes tutorial notebooks under `docs/tutorials/`)
20+
- CI workflows: `.github/workflows/`
21+
22+
## Supported Python
23+
24+
- Python >= 3.10 (see `pyproject.toml`).
25+
26+
## Setup (recommended: uv)
27+
28+
CI uses `uv sync` with `uv.lock`.
29+
30+
### Windows (PowerShell)
31+
32+
```powershell
33+
# From repo root
34+
pip install uv
35+
uv sync
36+
```
37+
38+
### macOS/Linux (bash)
39+
40+
```bash
41+
pip install uv
42+
uv sync
43+
```
44+
45+
## Run tests
46+
47+
### Full test suite
48+
49+
```powershell
50+
uv run --frozen pytest
51+
```
52+
53+
### Run a subset
54+
55+
```powershell
56+
uv run --frozen pytest tests/thermo
57+
uv run --frozen pytest -k "flash" -q
58+
```
59+
60+
### Disable Numba JIT (useful for determinism / faster CI-style coverage)
61+
62+
CI runs a second pass with JIT disabled.
63+
64+
```powershell
65+
$env:NUMBA_DISABLE_JIT = "1"
66+
uv run --frozen pytest
67+
```
68+
69+
To re-enable in the same shell:
70+
71+
```powershell
72+
Remove-Item Env:NUMBA_DISABLE_JIT -ErrorAction SilentlyContinue
73+
```
74+
75+
## Linting and formatting
76+
77+
Project config lives in `pyproject.toml`.
78+
79+
- Ruff (lint):
80+
81+
```powershell
82+
uv run ruff check .
83+
```
84+
85+
- Ruff (format):
86+
87+
```powershell
88+
uv run ruff format .
89+
```
90+
91+
If you change imports or add new modules, ensure Ruff import rules pass.
92+
93+
### (Optional) pre-commit hooks
94+
95+
This repo includes a `.pre-commit-config.yaml` that runs Ruff lint and format via `uv`.
96+
97+
```powershell
98+
uv run --frozen pre-commit install
99+
uv run --frozen pre-commit run --all-files
100+
```
101+
102+
## Documentation build
103+
104+
Docs build in CI using the `docs` dependency group:
105+
106+
```powershell
107+
uv sync --group docs
108+
uv run mkdocs build -d _site
109+
```
110+
111+
## Change workflow (agent-friendly)
112+
113+
1. Identify the smallest set of files needed.
114+
2. Implement the change.
115+
3. Run targeted tests first, then the full suite if the change is broad.
116+
4. Run `ruff check .` and `ruff format .` if you changed Python files.
117+
5. If docs are affected, run `mkdocs build`.
118+
119+
## Conventions
120+
121+
- Keep functions/classes type-annotated where practical.
122+
- Docstrings follow NumPy-style conventions (Ruff pydocstyle is enabled).
123+
- Respect the repo line length (90) when formatting.
124+
- Avoid adding new heavy dependencies without a clear need.
125+
126+
## CI parity notes
127+
128+
CI runs:
129+
130+
- `uv sync` (both highest and lowest-direct resolution)
131+
- `pytest` with and without Numba JIT
132+
- docs build via `mkdocs build`
133+
134+
When you need to replicate a CI failure locally, prefer running the exact `uv run --frozen ...` command.

‎docs/reference/copolymerization/index.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Copolymerization (polykin.copolymerization)
22

3+
[:simple-jupyter: Tutorial](../../tutorials/copolymerization){ .md-button }
4+
5+
## Overview
6+
37
This module implements methods and classes to model and analyze binary and
48
multicomponent copolymerization systems.
5-
6-
[:simple-jupyter: Tutorial](../../tutorials/copolymerization){ .md-button }

‎docs/reference/distributions/index.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Distributions (polykin.distributions)
22

3+
[:simple-jupyter: Tutorial](../../tutorials/distributions){ .md-button }
4+
5+
## Overview
6+
37
This module implements methods to create, visualize, fit, combine, integrate,
48
etc. theoretical and experimental chain-length distributions.
5-
6-
[:simple-jupyter: Tutorial](../../tutorials/distributions){ .md-button }

‎docs/reference/kinetics/coefficients/index.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Kinetic Coefficients (polykin.kinetics.coefficients)
22

3+
[:simple-jupyter: Tutorial](../../../tutorials/kinetic_coefficients){ .md-button }
4+
5+
## Overview
6+
37
This module implements methods to create and visualize the types of kinetic
48
coefficients most often used in polymer reactor models.
5-
6-
[:simple-jupyter: Tutorial](../../../tutorials/kinetic_coefficients){ .md-button }

0 commit comments

Comments
 (0)