Skip to content

Commit 14a8875

Browse files
jvachierjvachier
authored
Merge pull request #23 from jvachier/jv/improvement2
Overall improvement.
2 parents 7c0a040 + 8dd454d commit 14a8875

Some content is hidden

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

68 files changed

+6373
-844
lines changed

‎.github/workflows/README.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# CI/CD Pipeline
2+
3+
This directory contains GitHub Actions workflows for automated testing and validation.
4+
5+
## Workflows
6+
7+
### `ci.yml` - Continuous Integration Pipeline
8+
9+
Automated testing pipeline that runs on every push and pull request.
10+
11+
#### Jobs
12+
13+
1. **Unit Tests** (`unit-tests`)
14+
- Platform: Ubuntu Latest
15+
- Compiles and runs all unit tests
16+
- Tests boundary conditions and initialization modules
17+
- Uploads test results as artifacts
18+
19+
2. **CPU OpenMP Build** (`cpu-openmp`)
20+
- Platform: Ubuntu Latest
21+
- Builds CPU OpenMP version with g++-13
22+
- Runs smoke test with 10 particles
23+
- Validates no NaN values in output
24+
- Uploads executable and simulation results
25+
26+
3. **GPU Hybrid Build** (`gpu-hybrid-macos`)
27+
- Platform: macOS Latest (required for Metal support)
28+
- Builds GPU hybrid version with clang++
29+
- Tests CPU fallback mode with 100 particles
30+
- Validates Metal shader compilation
31+
- Checks for NaN-free output
32+
- Uploads executable and simulation results
33+
34+
4. **Benchmark Validation** (`benchmark-validation`)
35+
- Platform: macOS Latest
36+
- Validates benchmark script functionality
37+
- Runs minimal 3-way comparison (100 particles only)
38+
- Verifies Python visualization dependencies (uv, plotly, pandas)
39+
- Checks CSV output format
40+
41+
5. **Documentation Check** (`documentation-check`)
42+
- Platform: Ubuntu Latest
43+
- Verifies all README files exist
44+
- Validates LICENSE file (Apache 2.0)
45+
- Checks parameter.txt format (11 tab-separated values)
46+
- Detects broken relative links
47+
48+
6. **CI Success** (`ci-success`)
49+
- Summary job requiring all previous jobs to pass
50+
- Provides consolidated success message
51+
52+
## Triggers
53+
54+
The pipeline runs on:
55+
- **Push** to `main` or `jv/improvement2` branches
56+
- **Pull requests** to `main`
57+
- **Manual dispatch** via GitHub Actions UI
58+
59+
## Artifacts
60+
61+
Each job produces artifacts that are retained for 90 days:
62+
- `test-results` - Unit test executables
63+
- `cpu-openmp-build` - CPU version executable and output
64+
- `gpu-hybrid-macos-build` - GPU version executable and output
65+
- `benchmark-test-results` - Benchmark CSV data
66+
67+
## Local Testing
68+
69+
Run the same checks locally before pushing:
70+
71+
```bash
72+
# Unit tests
73+
cd tests
74+
make test
75+
76+
# CPU build
77+
cd cpu_openmp
78+
make clean && make
79+
echo -e "0.01\t1e-4\t10\t10.1\t0.0\t0.0\t15.0\t15.0\t10\t5\t2" > parameter.txt
80+
./abp_3D_confine.out
81+
82+
# GPU build (macOS only)
83+
cd gpu_hybrid
84+
make clean && make
85+
echo -e "0.01\t1e-4\t100\t10.1\t0.0\t0.0\t15.0\t15.0\t10\t5\t2" > parameter.txt
86+
./abp_3D_confine.out
87+
88+
# Check for NaN
89+
grep -q "nan" data/simulation.csv && echo "FAIL: NaN detected" || echo "PASS: No NaN"
90+
```
91+
92+
## Requirements
93+
94+
### Ubuntu Runners
95+
- build-essential
96+
- g++-13
97+
- libomp-dev
98+
99+
### macOS Runners
100+
- Xcode Command Line Tools
101+
- Homebrew (libomp)
102+
- Metal framework (built-in)
103+
104+
## Status Badge
105+
106+
Add to README.md:
107+
```markdown
108+
[![CI/CD](https://github.com/jvachier/active_particles_in_3D/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/jvachier/active_particles_in_3D/actions)
109+
```
110+
111+
## Troubleshooting
112+
113+
### Tests fail on Ubuntu but pass locally (macOS)
114+
- Check g++ version (requires g++-13+)
115+
- Verify OpenMP installation: `dpkg -l | grep libomp`
116+
117+
### GPU tests fail on macOS
118+
- Ensure libomp installed: `brew list libomp`
119+
- Check Metal shader exists: `test -f gpu_hybrid/particle_interactions.metal`
120+
121+
### Benchmark validation timeout
122+
- Reduce particle count in `benchmark_test.sh`
123+
- Current: 100 particles, 10 timesteps (takes ~1s)
124+
125+
### Documentation check fails
126+
- Verify parameter.txt has 11 fields: `awk -F'\t' '{print NF}' parameter.txt`
127+
- Check relative links in README files
128+
129+
## Contributing
130+
131+
When adding new features:
132+
1. Update unit tests if modifying core modules
133+
2. Ensure all tests pass locally before pushing
134+
3. Update documentation (README files)
135+
4. If adding new dependencies, update CI workflow
136+
137+
## Maintenance
138+
139+
Pipeline configuration is in YAML format. Key sections:
140+
- `on:` - Trigger conditions
141+
- `jobs:` - Individual test stages
142+
- `steps:` - Commands within each job
143+
- `needs:` - Job dependencies
144+
145+
To modify:
146+
1. Edit `.github/workflows/ci.yml`
147+
2. Test locally if possible
148+
3. Push to feature branch first
149+
4. Monitor Actions tab for results
150+
5. Merge to main after verification
151+
152+
---
153+
154+
**Last Updated**: November 2025
155+
**Maintainer**: Jeremy Vachier

‎.github/workflows/ci.yml‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
name: CI/CD Pipeline
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
workflow_dispatch:
9+
10+
jobs:
11+
# Unit Tests
12+
unit-tests:
13+
name: Unit Tests
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- name: Checkout code
18+
uses: actions/checkout@v4
19+
20+
- name: Install dependencies
21+
run: |
22+
sudo apt-get update
23+
sudo apt-get install -y build-essential g++-13 libomp-dev
24+
25+
- name: Build tests
26+
run: |
27+
cd tests
28+
make clean
29+
CXX=g++-13 make all
30+
31+
- name: Run unit tests
32+
run: |
33+
cd tests
34+
make test
35+
36+
- name: Upload test results
37+
if: always()
38+
uses: actions/upload-artifact@v4
39+
with:
40+
name: test-results
41+
path: tests/*.out
42+
43+
# CPU OpenMP Build
44+
cpu-openmp-build:
45+
name: CPU OpenMP Build
46+
runs-on: ubuntu-latest
47+
needs: unit-tests
48+
49+
steps:
50+
- name: Checkout code
51+
uses: actions/checkout@v4
52+
53+
- name: Install dependencies
54+
run: |
55+
sudo apt-get update
56+
sudo apt-get install -y build-essential g++-13 libomp-dev
57+
58+
- name: Build CPU OpenMP version
59+
run: |
60+
cd cpu_openmp
61+
make clean
62+
CC=g++-13 make
63+
64+
- name: Verify executable
65+
run: |
66+
cd cpu_openmp
67+
ls -lh abp_3D_confine.out
68+
file abp_3D_confine.out
69+
70+
# GPU Hybrid Build
71+
gpu-hybrid-build:
72+
name: GPU Hybrid Build (macOS)
73+
runs-on: macos-latest
74+
needs: unit-tests
75+
76+
steps:
77+
- name: Checkout code
78+
uses: actions/checkout@v4
79+
80+
- name: Install dependencies
81+
run: |
82+
brew install libomp
83+
84+
- name: Build GPU Hybrid version
85+
run: |
86+
cd gpu_hybrid
87+
make clean
88+
make
89+
90+
- name: Verify executable
91+
run: |
92+
cd gpu_hybrid
93+
ls -lh abp_3D_confine.out
94+
file abp_3D_confine.out
95+
96+
- name: Check Metal shader file
97+
run: |
98+
cd gpu_hybrid
99+
test -f particle_interactions.metal || exit 1
100+
wc -l particle_interactions.metal
101+
102+
# Documentation check
103+
documentation-check:
104+
name: Documentation Check
105+
runs-on: ubuntu-latest
106+
needs: unit-tests
107+
108+
steps:
109+
- name: Checkout code
110+
uses: actions/checkout@v4
111+
112+
- name: Check README exists
113+
run: |
114+
test -f README.md || exit 1
115+
test -f cpu_openmp/README.md || exit 1
116+
test -f gpu_hybrid/README.md || exit 1
117+
test -f docs/CODE_DOCUMENTATION.md || exit 1
118+
test -f tests/README.md || exit 1
119+
120+
- name: Check LICENSE file
121+
run: |
122+
test -f LICENCE || exit 1
123+
grep -q "Apache License" LICENCE || exit 1
124+
125+
- name: Validate parameter.txt format
126+
run: |
127+
# Check that parameter.txt files have 11 tab-separated values
128+
cd cpu_openmp
129+
test $(awk -F'\t' '{print NF}' parameter.txt) -eq 11 || exit 1
130+
cd ../gpu_hybrid
131+
test $(awk -F'\t' '{print NF}' parameter.txt) -eq 11 || exit 1
132+
133+
- name: Check for broken links in README
134+
run: |
135+
# Simple check for relative file references
136+
for file in README.md cpu_openmp/README.md gpu_hybrid/README.md; do
137+
echo "Checking $file..."
138+
# Extract relative links and verify files exist
139+
grep -o '\[.*\]([^)]*\.md)' $file | sed 's/.*(\(.*\))/\1/' | while read link; do
140+
if [[ $link != http* ]]; then
141+
dir=$(dirname $file)
142+
test -f "$dir/$link" || (echo "Broken link: $link in $file" && exit 1)
143+
fi
144+
done
145+
done
146+
147+
# Summary job
148+
ci-success:
149+
name: CI Success
150+
runs-on: ubuntu-latest
151+
needs: [unit-tests, cpu-openmp-build, gpu-hybrid-build, documentation-check]
152+
if: success()
153+
154+
steps:
155+
- name: Success message
156+
run: |
157+
echo "✅ All CI/CD checks passed!"
158+
echo ""
159+
echo "Summary:"
160+
echo " - Unit tests: PASSED"
161+
echo " - CPU OpenMP build: PASSED"
162+
echo " - GPU Hybrid build (macOS): PASSED"
163+
echo " - Documentation check: PASSED"

0 commit comments

Comments
 (0)