Reproducibility release: HF datasets/embeddings, fixed evaluators, reproduce scripts

.github/workflows/ci.yml

@@ -15,12 +15,13 @@ jobs:
         with:
           python-version: "3.11"
       - run: pip install ruff
-      - run: ruff check src/ tests/
-      - run: ruff format --check src/ tests/
+      - run: ruff check src/ tests/ examples/ reproduce/
+      - run: ruff format --check src/ tests/ examples/ reproduce/
 
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
     steps:
@@ -30,15 +31,15 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
+          python -m pip install --upgrade pip
           pip install -e ".[dev]"
-          pip install rdkit-pypi
       - name: Run tests
         run: pytest -m "not slow" --tb=short -q --cov=three_dbench --cov-report=xml
       - name: Upload coverage
         if: matrix.python-version == '3.11'
         uses: codecov/codecov-action@v4
         with:
           files: coverage.xml
-          fail_ci_if_not_required: false
+          fail_ci_if_error: false
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -49,3 +49,6 @@ examples/.demo_cache/
 
 # Claude Code local settings
 .claude/
+
+# Reproduction script outputs
+reproduce/*/out/

CITATION.cff

@@ -0,0 +1,42 @@
+cff-version: 1.2.0
+message: "If you use 3DCS, please cite the ICLR 2026 paper."
+title: "3DCS: Datasets and Benchmark for Evaluating Conformational Sensitivity in Molecular Representations"
+type: software
+license: MIT
+repository-code: "https://github.com/ComDec/3DCS"
+url: "https://openreview.net/forum?id=JAb0y8lkqL"
+authors:
+  - family-names: Wang
+    given-names: Xi
+  - family-names: Zhang
+    given-names: Yang
+  - family-names: Zhang
+    given-names: Yingjia
+  - family-names: Cai
+    given-names: Yejia
+  - family-names: Wang
+    given-names: Shengjie
+keywords:
+  - molecular representation learning
+  - conformers
+  - chirality
+  - benchmark
+preferred-citation:
+  type: conference-paper
+  title: "3DCS: Datasets and Benchmark for Evaluating Conformational Sensitivity in Molecular Representations"
+  authors:
+    - family-names: Wang
+      given-names: Xi
+    - family-names: Zhang
+      given-names: Yang
+    - family-names: Zhang
+      given-names: Yingjia
+    - family-names: Cai
+      given-names: Yejia
+    - family-names: Wang
+      given-names: Shengjie
+  collection-title: "The Fourteenth International Conference on Learning Representations (ICLR 2026)"
+  conference:
+    name: "International Conference on Learning Representations (ICLR)"
+  year: 2026
+  url: "https://openreview.net/forum?id=JAb0y8lkqL"

CONTRIBUTING.md

@@ -14,12 +14,10 @@ cd 3DCS
 python -m venv .venv
 source .venv/bin/activate
 
-# Install in editable mode with dev dependencies
+# Install in editable mode with dev dependencies (RDKit comes from the `rdkit` package on PyPI;
+# do not install `rdkit-pypi`)
 pip install -e ".[dev]"
 
-# Install RDKit (required for molecule parsing)
-pip install rdkit-pypi
-
 # Install pre-commit hooks
 pre-commit install
 ```
@@ -37,19 +35,21 @@ pytest --cov=three_dbench
 pytest -m "not slow"
 ```
 
+CI runs `pytest -m "not slow"` on Python 3.9, 3.10, 3.11 and 3.12.
+
 ## Code Style
 
 This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting.
 
 ```bash
-# Check for issues
-ruff check src/ tests/
+# Check for issues (the same paths as CI and `make lint`)
+ruff check src/ tests/ examples/ reproduce/
 
 # Auto-fix issues
-ruff check --fix src/ tests/
+ruff check --fix src/ tests/ examples/ reproduce/
 
 # Format code
-ruff format src/ tests/
+ruff format src/ tests/ examples/ reproduce/
 ```
 
 Key style rules:
@@ -65,6 +65,8 @@ Key style rules:
 4. Add a benchmark entry point in `src/three_dbench/benchmarks/my_task.py`
 5. Register the task in `src/three_dbench/__main__.py`
 6. Add tests under `tests/`
+7. Document the metric definitions under `docs/metrics/` and, if the task reproduces a paper table,
+   add `reproduce/<table>/` with `run.sh` and `expected.csv` (see `reproduce/README.md`)
 
 ## Submitting Changes
 

Makefile

@@ -5,19 +5,20 @@ install:
 
 dev:
 	pip install -e ".[dev]"
-	pip install rdkit-pypi
 	pre-commit install
 
 test:
 	pytest
 
+LINT_PATHS = src/ tests/ examples/ reproduce/
+
 lint:
-	ruff check src/ tests/
-	ruff format --check src/ tests/
+	ruff check $(LINT_PATHS)
+	ruff format --check $(LINT_PATHS)
 
 format:
-	ruff check --fix src/ tests/
-	ruff format src/ tests/
+	ruff check --fix $(LINT_PATHS)
+	ruff format $(LINT_PATHS)
 
 clean:
 	rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache htmlcov/