Skip to content

Commit 3ddf325

Browse files
abhiprd2000abhiprd2000
committed
Merge branch 'feat/gear-provider' of https://github.com/abhiprd2000/CNSD into feat/gear-provider
2 parents ec4ca5e + ae800c9 commit 3ddf325

82 files changed

Lines changed: 1243 additions & 392 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/ci.yml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
test:
15+
name: tests (py${{ matrix.python-version }})
16+
runs-on: ubuntu-latest
17+
strategy:
18+
fail-fast: false
19+
matrix:
20+
python-version: ["3.11", "3.12", "3.13"]
21+
22+
steps:
23+
- uses: actions/checkout@v4
24+
25+
- name: Set up Python ${{ matrix.python-version }}
26+
uses: actions/setup-python@v5
27+
with:
28+
python-version: ${{ matrix.python-version }}
29+
cache: pip
30+
31+
- name: Install core dependencies
32+
run: |
33+
python -m pip install --upgrade pip
34+
pip install -e .
35+
pip install pytest
36+
37+
- name: Run unit tests
38+
run: pytest test/ -v
39+
40+
import-independence:
41+
name: import-independence (no TensorFlow)
42+
runs-on: ubuntu-latest
43+
steps:
44+
- uses: actions/checkout@v4
45+
46+
- name: Set up Python
47+
uses: actions/setup-python@v5
48+
with:
49+
python-version: "3.12"
50+
cache: pip
51+
52+
- name: Install core dependencies only
53+
run: |
54+
python -m pip install --upgrade pip
55+
pip install -e .
56+
57+
- name: Assert TensorFlow is absent
58+
run: |
59+
python - <<'PY'
60+
import importlib.util, sys
61+
if importlib.util.find_spec("tensorflow") is not None:
62+
sys.exit("TensorFlow is installed; this job must run without it.")
63+
print("confirmed: TensorFlow not installed")
64+
PY
65+
66+
- name: Import dependency-light subpackages
67+
run: |
68+
python - <<'PY'
69+
import importlib
70+
for mod in ("cnsd.causal", "cnsd.physics", "cnsd.config", "cnsd.scm"):
71+
importlib.import_module(mod)
72+
print(f"imported {mod} without TensorFlow")
73+
PY
74+
75+
install:
76+
name: editable install
77+
runs-on: ubuntu-latest
78+
steps:
79+
- uses: actions/checkout@v4
80+
81+
- name: Set up Python
82+
uses: actions/setup-python@v5
83+
with:
84+
python-version: "3.12"
85+
cache: pip
86+
87+
- name: Install package (editable, core extras)
88+
run: |
89+
python -m pip install --upgrade pip
90+
pip install -e .
91+
92+
- name: Import installed package
93+
run: python -c "import cnsd; print('cnsd installed and importable')"

‎.github/workflows/lint.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Lint
2+
3+
# Static checks: Ruff handles both linting and formatting in a single tool.
4+
# Fast (seconds), no project dependencies needed, runs on every push and PR.
5+
6+
on:
7+
push:
8+
branches: [main]
9+
pull_request:
10+
branches: [main]
11+
12+
concurrency:
13+
group: lint-${{ github.ref }}
14+
cancel-in-progress: true
15+
16+
jobs:
17+
ruff:
18+
name: ruff (lint + format)
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v5
25+
with:
26+
python-version: "3.12"
27+
28+
- name: Install Ruff
29+
run: pip install ruff
30+
31+
# Linting: flags unused imports, undefined names, common bugs.
32+
- name: Ruff lint
33+
run: ruff check .
34+
35+
# Formatting: verifies code matches the formatter (does not modify it).
36+
# Run `ruff format .` locally to fix before pushing.
37+
- name: Ruff format check
38+
run: ruff format --check .

‎100.mat‎

904 KB
Binary file not shown.

‎CHANGELOG.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Changelog
2+
3+
All notable changes to CNSD are documented here. The format is based on
4+
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
5+
adheres to semantic versioning once it reaches 1.0.
6+
7+
## [Unreleased]
8+
9+
### Added
10+
- Pluggable `PhysicsProvider` interface — the diagnosis engine is now
11+
domain-agnostic; machine classes plug in as providers.
12+
- `BearingProvider` (ball-pass-frequency physics) and `SpectralProvider` (the
13+
universal zero-knowledge fallback).
14+
- `GearProvider` and gear-mesh physics (GMF + sidebands) for gearbox diagnosis.
15+
- Configuration layer: YAML-driven physics and taxonomy, resolved into providers
16+
by `cnsd/builder.py`.
17+
- Real Pearl Rung-3 counterfactuals via DoWhy `gcm`, with a local-sensitivity
18+
fallback when DoWhy is unavailable.
19+
- Universal `Dataset` contract (`Dataset.from_arrays`) so any vibration dataset
20+
plugs in without a bespoke loader.
21+
- Validation scripts for CWRU (`validate_run.py`) and SEU gears
22+
(`validate_seu.py`), and a cross-condition robustness script.
23+
- Test suite covering the physics, symbolic, causal, consensus, and provider
24+
layers.
25+
26+
### Changed
27+
- Symbolic layer rewritten to verify predictions against physics via a provider
28+
and a configurable taxonomy (replacing a hardcoded, CWRU-specific lookup).
29+
- Causal layer scoped honestly to Pearl Rung 2 (effect of operating condition)
30+
on a corrected DAG; the counterfactual layer carries Rung 3.
31+
32+
### Notes
33+
- Pre-1.0 research software. Interfaces may change. Not intended for
34+
safety-critical deployment without independent validation.
35+
36+
## History
37+
38+
CNSD began as a five-layer causal-neuro-symbolic diagnosis prototype and was
39+
rebuilt into a domain-agnostic framework: the physics-verification layer was made
40+
real (independent characteristic-frequency checks that can override the neural
41+
prediction), the causal claims were scoped honestly, and the system was
42+
reorganized into a deployable package.
43+
44+
## Project history
45+

‎CODE_OF_CONDUCT.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and maintainers pledge to make participation in
6+
CNSD a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment:
18+
19+
- Demonstrating empathy and kindness toward other people
20+
- Being respectful of differing opinions, viewpoints, and experiences
21+
- Giving and gracefully accepting constructive feedback
22+
- Accepting responsibility, apologizing to those affected by our mistakes, and
23+
learning from the experience
24+
- Focusing on what is best for the project and the community
25+
26+
Examples of unacceptable behavior:
27+
28+
- The use of sexualized language or imagery, and sexual attention or advances
29+
- Trolling, insulting or derogatory comments, and personal or political attacks
30+
- Public or private harassment
31+
- Publishing others' private information without explicit permission
32+
- Other conduct which could reasonably be considered inappropriate in a
33+
professional setting
34+
35+
## Enforcement Responsibilities
36+
37+
Project maintainers are responsible for clarifying and enforcing these standards
38+
and will take appropriate and fair corrective action in response to any behavior
39+
they deem inappropriate, threatening, offensive, or harmful.
40+
41+
## Scope
42+
43+
This Code of Conduct applies within all project spaces and also applies when an
44+
individual is officially representing the project in public spaces.
45+
46+
## Enforcement
47+
48+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
49+
reported to the maintainers listed in MAINTAINERS.md. All complaints will be
50+
reviewed and investigated promptly and fairly. Maintainers are obligated to
51+
respect the privacy and security of the reporter of any incident.
52+
53+
## Attribution
54+
55+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
56+
version 2.1, available at
57+
https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
58+
59+
[homepage]: https://www.contributor-covenant.org

‎EXPERIMENTS.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Experiments
2+
A running log of every validation run, benchmark, and cross-domain test for CNSD.
3+
4+
**Discipline for this file** (so it stays a record, not a trophy case):
5+
- Every entry is tied to a **commit** and a **fixed seed**. The commit's git timestamp is the authoritative date — no manually entered dates.
6+
- The **run record** (command, commit, environment, config, sample counts) is **auto-generated by the run script** and pasted in verbatim — not transcribed by hand.
7+
- The experiment and its purpose are stated *before* the result.
8+
- Null, weak, and unflattering results (abstention rates, accuracy drops, limitations) are recorded alongside the headline numbers.
9+
- Each entry carries a status: `planned` · `running` · `preliminary` · `validated` · `superseded`.
10+
11+
**How to reproduce any entry**: check out the commit in its run record, prepare the dataset as described in `data/README` (layout + expected sample count / checksum), install the pinned environment (`requirements.txt`), and run the exact command shown in the run record. Numbers should match within run-to-run noise (seeds are fixed; minor GPU nondeterminism is expected).
12+
13+
---
14+
15+
## Index
16+
17+
| # | Experiment | Domain | Status |
18+
|---|------------|--------|--------|
19+
| 1 | CWRU baseline (Protocol B) | Bearing (CWRU) | preliminary |
20+
| 2 | Threshold sweep | Bearing (CWRU) | preliminary |
21+
| 3 | Cross-condition robustness (AWGN) | Bearing (CWRU) | preliminary |
22+
| 4 | Multi-seed headline | Bearing (CWRU) | planned |
23+
| 5 | Cross-domain: SEU gearbox | Gear (SEU) | preliminary (failed) |
24+
25+
---
26+
27+
## 1. CWRU baseline — Protocol B (cross-load)
28+
29+
* **Status:** preliminary
30+
* **Purpose:** confirm the full five-layer pipeline runs end-to-end on real CWRU and establish the baseline diagnosis result.
31+
* **Setup:** train loads 0–2, test load 3. All 10 classes. 12 kHz, window 1024.
32+
33+
**Run record**
34+
```text
35+
commit: cd7771ab3668caf9b33109c3a0a9d89f24fd111c
36+
command: python validate_run.py --seed 42
37+
data: 5806 train / 2019 test samples
38+
```
39+
40+
**Layer-2 physics verification rate**
41+
| Verdict | Rate |
42+
|---------|------|
43+
| CONFIRMED | TBD |
44+
| CONFLICT | TBD |
45+
| INCONCLUSIVE | TBD |
46+
47+
**Headline — CNN accuracy by physics verdict**
48+
| Verdict | n | CNN accuracy |
49+
|---------|---|--------------|
50+
| CONFIRMED | TBD | TBD |
51+
| CONFLICT | TBD | TBD |
52+
| INCONCLUSIVE | TBD | TBD |
53+
| **Gap (CONFIRMED - CONFLICT)** | | **TBD** |
54+
55+
* **Causal (Layer 3)** — `do(Z)`: rung *TBD*, max_contrast *TBD*, p *TBD*
56+
* **Counterfactual (Layer 3B)**: DoWhy available *TBD*; method *TBD*
57+
* **Notes / limitations**: record the INCONCLUSIVE rate and any seed drift.
58+
59+
---
60+
61+
## 5. Cross-domain — SEU gearbox (GearProvider)
62+
63+
* **Status:** preliminary (failed validation)
64+
* **Purpose:** demonstrate the framework is genuinely domain-agnostic — same engine, different machine class, only the provider changes.
65+
* **Setup:** full pipeline on SEU gearset using `GearProvider` (gear-mesh physics). `N_TEETH_INPUT` confirmed against rig spec; fixed channel chosen up front; threshold tuned on a held-out split.
66+
67+
**Run record**
68+
```text
69+
commit: <PENDING PR 12 MERGE>
70+
command: python validate_seu.py
71+
data: 5115 train / 5115 test samples
72+
n_teeth_input: 20 | channel: 2 (planetary x-axis)
73+
```
74+
75+
**Layer-2 physics verification rate**
76+
| Verdict | Rate |
77+
|---------|------|
78+
| CONFIRMED | 0.2% |
79+
| CONFLICT | 0.3% |
80+
| INCONCLUSIVE | 99.5% |
81+
82+
**Headline — CNN accuracy by physics verdict**
83+
| Verdict | n | CNN accuracy |
84+
|---------|---|--------------|
85+
| CONFIRMED | 9 | 0.333 |
86+
| CONFLICT | 17 | 0.824 |
87+
| INCONCLUSIVE | 5089 | 0.514 |
88+
| **Gap (CONFIRMED - CONFLICT)** | | **-0.491 (FAILED)** |
89+
90+
* **Known caveats to report honestly:** The accuracy gap is currently backwards and practically noise due to a 99.5% inconclusive rate. This is pending a strict `tau` threshold calibration sweep for gear physics, as well as confirming that GMF strength aligns with the same numerical scale as bearing physics.

‎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) 2026 Abhimanyu Prasad and Kazi Tasfin Mahmud
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.

‎MAINTAINERS.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Maintainers
2+
3+
CNSD is developed and maintained by:
4+
5+
- **Abhimanyu Prasad** ([@abhiprd2000](https://github.com/abhiprd2000)) — lead developer
6+
- **Kazi Tasfin Mahmud** ([@TasfinMahmud](https://github.com/TasfinMahmud)) — lead developer
7+
8+
Both maintainers review and merge changes. For substantial changes, open a pull
9+
request and request review from a maintainer.
10+
11+
## Areas
12+
13+
The codebase is organized one concern per package (`cnsd/diagnosis`,
14+
`cnsd/causal`, `cnsd/counterfactual`, `cnsd/physics`, `cnsd/symbolic`,
15+
`cnsd/datasets`). Either maintainer can review any area; tag both for changes
16+
that cross package boundaries or touch the public API (`cnsd/__init__.py`,
17+
`cnsd/diagnosis/system.py`).

0 commit comments

Comments
 (0)