alomancy 0.2.0__tar.gz

alomancy-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,214 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main, master, develop ]
+  pull_request:
+    branches: [ main, master, develop ]
+  release:
+    types: [published]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-lint-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-lint-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/alomancy/core src/alomancy/analysis src/alomancy/configs src/alomancy/utils src/alomancy/high_accuracy_evaluation src/alomancy/mlip src/alomancy/structure_generation tests
+
+      - name: Check formatting with ruff
+        run: ruff format --check src/alomancy/core src/alomancy/analysis src/alomancy/configs src/alomancy/utils src/alomancy/high_accuracy_evaluation src/alomancy/mlip src/alomancy/structure_generation tests
+
+      - name: Type check with mypy
+        run: mypy src/alomancy
+        continue-on-error: true  # Allow to continue if mypy fails
+
+  test:
+    runs-on: ${{ matrix.os }}
+    needs: lint  # Run tests after linting passes
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+        exclude:
+          # Exclude some combinations to reduce CI time
+          - os: macos-latest
+            python-version: "3.11"
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Cache pip packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-py${{ matrix.python-version }}-pip-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-py${{ matrix.python-version }}-pip-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Test with pytest
+      run: |
+        pytest --cov=alomancy --cov-report=xml --cov-fail-under=70 -v tests/
+      env:
+        ALOMANCY_TEST_MODE: "1"
+        ALOMANCY_MOCK_EXTERNAL: "1"
+
+    - name: Upload coverage to Codecov
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.10'
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+
+  integration-test:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Cache pip packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-integration-pip-${{ hashFiles('**/pyproject.toml') }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run integration tests
+      run: |
+        pytest -m integration tests/ -v
+      env:
+        ALOMANCY_TEST_MODE: "1"
+        ALOMANCY_MOCK_EXTERNAL: "1"
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    if: github.event_name == 'release' || github.event_name == 'push'
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Needed for setuptools_scm
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'release'
+    environment: release  # Use environment protection
+
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}
+
+  documentation:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Cache pip packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-docs-pip-${{ hashFiles('**/pyproject.toml') }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[docs]"
+
+    - name: Build documentation
+      id: build_docs
+      run: sphinx-build -b html docs docs/_build/html
+      continue-on-error: true
+
+    - name: Deploy to GitHub Pages
+      if: steps.build_docs.outcome == 'success'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html

alomancy-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+*traj
+*xyz
+*log
+
+mace_general
+results
+working_demo
+MACE_model
+archive
+dist
+build
+version.py
+*.egg-info
+*.egg
+__pycache__
+src/alomancy.egg-info/SOURCES.txt
+src/alomancy.egg-info/dependency_links.txt

alomancy-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+# Minimal pre-commit configuration
+repos:
+  # General code quality
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-toml
+      - id: debug-statements
+
+  # Python formatting and linting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.15
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Fast unit tests only
+  - repo: local
+    hooks:
+      - id: pytest-unit
+        name: Unit tests
+        entry: pytest
+        language: system
+        pass_filenames: false
+        always_run: true
+        args: [-m, "not integration and not slow", --tb=line, -q, tests/]
+        stages: [pre-commit]
+
+exclude: |
+  (?x)^(
+      \.git/|
+      __pycache__/|
+      build/|
+      dist/|
+      \.venv/|
+      src/alomancy/_?version\.py
+  )

alomancy-0.2.0/.readthedocs.yaml

@@ -0,0 +1,22 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+formats:
+  - pdf
+  - htmlzip

alomancy-0.2.0/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-13
+
+### Added
+- **Per-fit validation set carving**: `mace_fit` now carves a per-committee-member held-out validation set from the training data before calling MACE. Eligible structures are those with `config_type` in `mlip_committee.valid_config_types` (defaults to `initialization.test_config_types`) or `"high_sd"`. Fraction is controlled by `mlip_committee.valid_fraction` (default 0.05). When no eligible structures exist or the fraction rounds to zero, MACE is pointed directly at the shared `train_set.xyz` without writing a redundant copy. Each member uses seed `seed + fit_idx` for reproducible but distinct splits. The helper `_select_validation_split` is module-level for testability.
+- **Log-scale MAE plots**: `mae_al_loop_plot` now renders the y-axis on a log scale, making error improvements across orders of magnitude visible across many AL loops.
+- **Pluggable DFT backend**: `high_accuracy_evaluation` now supports multiple calculators via a `calculator` config key (default `"qe"`). The registry in `high_accuracy_evaluation/dft/__init__.py` resolves `(run_sp_fn, run_go_fn)` at runtime with lazy imports, so installing only one calculator does not break the other.
+- **VASP backend** (`high_accuracy_evaluation/dft/run_vasp.py`): `run_sp_vasp` / `run_go_vasp` mirror the QE interface exactly. `create_vasp_calc_object` builds a `Vasp` calculator with sensible INCAR defaults (PBE, ENCUT=500, non-self-consistent geometry relaxation via BFGS). Monkhorst-Pack k-points derived from the cell via the shared `generate_kpts` utility.
+- **Shared DFT utilities** (`utils/dft_utils.py`): `generate_kpts`, `_build_srun_command`, `_run_sp`, and `_run_go` extracted from `run_qe.py` and shared by both backends. Neither backend duplicates this logic.
+- **Mismatched-kwargs warning**: `warn_mismatched_kwargs(calculator, job_dict)` logs a WARNING when config keys belonging to a different calculator (e.g. `vasp_input_kwargs` in a QE run) are present, so misconfigured YAMLs are caught early.
+- **`high_sd` config_type for AL loop structures**: Structures returned by `high_accuracy_evaluation` are now tagged `config_type="high_sd"` with `atoms.info["al_loop"] = <loop>` metadata, replacing the previous `al_loop_N` per-loop types. This gives a stable, queryable label across all loops.
+- **GlobalDatabase**: Persistent sage_lib Partition (hybrid HDF5+SQLite) storing all DFT-evaluated structures across AL loops. Deduplication by (config_type, formula) prevents double-adding IsolatedAtom and init_MP entries from multiple datasets. REF_forces arrays serialised into atoms.info for round-trip storage.
+- **DB-aware initialization**: `compute_initialization_needs()` queries the GlobalDatabase to determine what structures still need to be generated before starting DFT. Replaces the old `d_t_s_a_ratio` + `target_non_mp_structures_to_add` API with explicit per-type counts: `num_dimers_per_combo`, `num_trimers_per_combo`, `num_amorphous`, `num_stretch_compress_per_mp`.
+- **Structured logging**: All 108 `print()` calls replaced with Python `logging` module. `setup_logging(verbose, log_file)` called once at workflow construction. verbose=0 silences console; verbose=1 shows INFO progress; verbose=2 shows DEBUG per-job detail. File handler always captures DEBUG regardless of verbose level. ExPyRe job stdout/stderr captured at DEBUG.
+- **Extra dataset seeding**: Extra datasets are now seeded into the GlobalDatabase *before* `initialize_training_set` is called, so `compute_initialization_needs` accounts for them and avoids regenerating already-provided structures.
+- `log_file` parameter on `BaseActiveLearningWorkflow` (default: `"results/alomancy.log"`)
+- `db_path` parameter on `BaseActiveLearningWorkflow` (default: `"results/global_database"`)
+- Warning if structure generation could contain single-atom structures
+- `"high_sd"` is automatically appended to `selectable_configs` in `select_initial_structures` so that structures from previous AL loops are always eligible for seeding MD, even when `selectable_configs` is explicitly set.
+
+### Changed
+- `train_mlip` abstract method and `ActiveLearningStandardMACE` implementation now receive the full `job_dict` (all four top-level keys) instead of `mlip_committee_job_dict`. `mace_fit` likewise takes `job_dict` so it can read `initialization.test_config_types` as the default validation config types.
+- `ase_remote_submitter` replaces `qe_remote_submitter`; output directories use `ase_output_` prefix instead of `qe_output_`. The interface is otherwise unchanged.
+- `run_qe.py` imports `generate_kpts` and shared runner helpers from `utils/dft_utils.py` instead of defining them locally.
+- AL loop structures now carry `config_type="high_sd"` (stable across loops) rather than `config_type="al_loop_N"` (loop-specific). The originating loop is preserved in `atoms.info["al_loop"]`.
+- Initialization configuration now uses per-type counts instead of ratio-based approach.
+- `initialize_training_set` now has a DB-aware path that only generates missing structures.
+- Logging replaces all bare print() calls; no external API change.
+
+### Fixed
+- `select_initial_structures` no longer mutates `Atoms` objects in `train_atoms_list`; selected structures are `.copy()`-d before `mark_structures_for_dft` writes to them. Previously, marking corrupted `config_type` on shared references, causing the `selectable_configs` filter to find zero matches on subsequent AL loops.
+- Batch numbering collision between GO (geometry-optimisation) and SP (single-point) DFT jobs.
+
+### Dependencies
+- Added: sage-lib (HDF5+SQLite storage backend for GlobalDatabase)
+- Added: polars (Polars DataFrame used in structure generation std-dev calculations)
+
+
+## [0.1.1] - 2025-08-14
+
+### Added
+- Initial changelog documentation
+- Optional extra dictionaries to control function behaviour inside core funcitons
+- CI/CD for precommit hooks
+- read the docs documentation
+
+### Changed
+- Improved package documentation and examples
+- Improved testing
+- Folded eval MLIP into the mlip_committee function
+- mlip_committee now returns a pd.Dataframe of mae_e and mae_f for each loop
+- ruff formatting for everything
+
+
+## [0.1.0] - 2025-08-13
+
+### Added
+- Initial release of ALomancy package
+- Standard MACE active learning workflow (`ActiveLearningStandardMACE`)
+- Support for remote job execution via ExPyRe
+- Structure generation using molecular dynamics
+- MLIP committee training and evaluation
+- High-accuracy DFT evaluation pipeline with Quantum Espresso
+- Configuration management for HPC systems
+- Example workflows and configuration files
+
+### Features
+- **Core Workflows**
+  - Base active learning framework
+  - MACE-specific implementation
+  - Configurable loop iteration
+
+- **Structure Generation**
+  - Initial structure selection
+  - Molecular dynamics simulations
+  - High standard deviation structure identification
+
+- **Machine Learning**
+  - MACE model training and committee evaluation
+  - Uncertainty quantification
+  - Model performance metrics
+
+- **Remote Execution**
+  - HPC job submission and monitoring
+  - Queue system integration
+  - Automatic result collection
+
+- **Configuration**
+  - YAML-based job configuration
+  - HPC system definitions
+  - Flexible parameter management
+
+[Unreleased]: https://github.com/your-username/alomancy/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/your-username/alomancy/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/your-username/alomancy/releases/tag/v0.1.0

alomancy-0.2.0/CLAUDE.md

@@ -0,0 +1,143 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install in development mode (required before anything else)
+pip install -e ".[dev]"
+
+# Lint and format
+ruff check src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/alomancy
+
+# Run all tests (fast — skips coverage overhead)
+/home/jholl/.venvs/al_install/bin/pytest --no-cov
+
+# Run only unit tests (no HPC/MACE/QE/MP required)
+/home/jholl/.venvs/al_install/bin/pytest -m unit --no-cov
+
+# Run a single test file
+/home/jholl/.venvs/al_install/bin/pytest tests/core_tests/test_base_active_learning.py --no-cov
+
+# Run by marker
+pytest -m "not requires_external"
+
+# Run with coverage (slow — pyproject.toml sets --cov-fail-under=80)
+pytest --cov=alomancy --cov-report=html
+
+# Run in CI mode (env vars disable real external calls)
+ALOMANCY_TEST_MODE=1 ALOMANCY_MOCK_EXTERNAL=1 pytest tests/
+```
+
+Pre-commit hooks run `ruff` (with `--fix`) and unit tests on every commit. Install with `pre-commit install`.
+
+## Logging
+
+All output goes through Python's `logging` module. No bare `print()` calls exist in `src/`.
+
+```python
+# Single configuration point — called in BaseActiveLearningWorkflow.__init__
+from alomancy.utils.logging_config import setup_logging
+setup_logging(verbose=1, log_file="results/my_run.log")
+```
+
+| `verbose` | Console | File (`results/alomancy.log`) |
+|---|---|---|
+| 0 (default) | WARNING+ only | DEBUG always |
+| 1 | INFO (step progress) | DEBUG always |
+| 2+ | DEBUG (per-job detail) | DEBUG always |
+
+The file handler always writes DEBUG so every run produces a complete timestamped record. ExPyRe job stdout/stderr are captured at DEBUG level.
+
+Each module declares `logger = logging.getLogger(__name__)` — no per-module setup needed. The `"expyre"` logger is also routed through the same handlers.
+
+**Testing logs:** pytest's `caplog` does not intercept alomancy logs because `propagate=False` is set on the root alomancy logger. Attach a `logging.Handler` directly to `logging.getLogger("alomancy")` in tests that need to assert on log output (see `test_seed_logs_message` in `test_base_active_learning.py`).
+
+## Architecture
+
+ALomancy implements active learning (AL) workflows for training machine-learned interatomic potentials (MLIPs). The core loop is: **train MLIP committee → MD structure generation → uncertainty-based selection → DFT evaluation → extend training set → repeat**.
+
+### Core layer (`src/alomancy/core/`)
+
+`BaseActiveLearningWorkflow` (abstract) owns the AL loop in its `run()` method. It calls four abstract methods that concrete subclasses must implement:
+
+- `initialize_training_set(base_name)` — produce initial `(train_xyzs, test_xyzs)` atom lists
+- `train_mlip(base_name, job_dict)` → `pd.DataFrame` of evaluation metrics
+- `generate_structures(base_name, job_dict, train_atoms_list)` → `list[Atoms]` of high-uncertainty candidates
+- `high_accuracy_evaluation(base_name, job_dict, structures)` → `list[Atoms]` with DFT results
+
+`ActiveLearningStandardMACE` (in `standard_active_learning.py`) is the production implementation: MACE committee for the MLIP, ASE MD for structure generation, Quantum Espresso (QE) for DFT.
+
+All results land under `results/<base_name>/` with a fixed subdirectory layout. The workflow has **idempotency logic** throughout: each step checks for existing output files and skips remote submission if they exist, enabling restart after failures.
+
+### Configuration (`src/alomancy/configs/`)
+
+`load_dictionaries(config_path)` reads a YAML file into a `jobs_dict` passed to the workflow constructor. Three top-level keys are required: `initialization`, `mlip_committee`, `structure_generation`, `high_accuracy_evaluation`. Each carries a `name`, `max_time`, and `hpc` sub-dict (`hpc_name`, `partitions`, `pre_cmds`).
+
+`RemoteInfo` and `get_remote_info()` convert a job sub-dict into an Expyre `RemoteInfo` object. The `sys_name` field maps to an Expyre system name (defined in the user's Expyre config, not in this repo).
+
+### Remote execution (`src/alomancy/utils/remote_job_executor.py`)
+
+`RemoteJobExecutor` wraps Expyre's `ExPyRe`. Call pattern: `submit_multiple_jobs → start_all_jobs → wait_for_all_jobs → cleanup_jobs`. The convenience method `run_and_wait` does all four steps. **Note**: `wait_for_all_jobs` is intentionally called twice in `run_and_wait` to ensure results sync locally from the remote.
+
+**Remote deployment**: ExPyRe serializes functions **by reference** (module path + function name). The remote machine imports the module to resolve the function at run time. When changing the signature or body of any function submitted remotely (e.g. `mace_fit`), you must reinstall the updated package on the remote machine (`pip install -e .` there) before restarting, or jobs will import the old code and fail with a `TypeError` at the call site — typically hours after submission.
+
+### Module responsibilities
+
+| Module | Purpose |
+|---|---|
+| `database/global_database.py` | `GlobalDatabase` — persistent sage_lib `Partition` (hybrid HDF5+SQLite) storing all post-DFT structures; handles dedup by `(config_type, formula)` and forces round-trip via `atoms.info['_REF_forces']` |
+| `initialize/initialization_structure_list.py` | `create_initialization_atoms_list()` generates initial structures (dimers, trimers, amorphous, MP); `compute_initialization_needs()` queries the DB and returns per-combo counts of what's still missing |
+| `initialize/mp_interface.py` | Fetches structures from the Materials Project API (`mp_api`) |
+| `mlip/committee_remote_submitter.py` | Submits N MACE training jobs (committee); each fit lands in `results/<base>/mlip_committee/fit_<i>/` |
+| `mlip/mace_wfl.py` | Wraps the `mace_fit` CLI call for a single committee member |
+| `mlip/get_mace_eval_info.py` | Reads trained MACE model error metrics into a DataFrame |
+| `structure_generation/md/md_remote_submitter.py` | Submits MD runs (one per input structure) and force-evaluation jobs across all committee members |
+| `structure_generation/find_high_sd_structures.py` | Selects structures with highest force standard-deviation across the committee (uncertainty metric); uses Polars DataFrames |
+| `structure_generation/select_initial_structures.py` | Picks seed structures from training data for MD |
+| `high_accuracy_evaluation/dft/qe_remote_submitter.py` | Batches structures and submits QE jobs; supports both single-point (`run_sp_qe`) and geometry-optimisation (`run_go_qe`) |
+| `utils/clean_structures.py` | Validates/cleans ASE Atoms objects after DFT (sets `config_type`, removes bad structures) |
+| `utils/test_train_manager.py` | Splits atom lists into train/test and merges extra datasets |
+| `analysis/plotting.py` | Plots MAE vs AL loop number |
+
+### Key conventions
+
+- All file I/O uses `extxyz` format via ASE's `read`/`write`.
+- Energy and force labels stored in `atoms.info["REF_energy"]` and `atoms.arrays["REF_forces"]`. **Never use bare `"energy"` as an info key** — ASE moves it to the calculator on extxyz read, losing it from `atoms.info`.
+- Structures that need geometry optimisation carry `atoms.info["needs_relaxation"] = True`.
+- `config_type` in `atoms.info` tracks provenance (e.g. `"initialization"`, `"init_dimer"`, `"high_sd"`). Structures selected by the AL loop uncertainty criterion get `config_type="high_sd"` (set by `clean_structures` in `base_active_learning.run()`); the per-loop index is stored separately in `atoms.info["al_loop"]` via `extra_metadata`. Do not use `"al_loop_N"` as a config_type — the loop number is not embedded in the type string.
+- The `seed` parameter (default `803`) is used everywhere randomness appears for reproducibility.
+- `verbose` is an int: `0` = silent, `>0` = progress prints.
+- The global DB lives at `results/global_database/` (configurable via `db_path` in `BaseActiveLearningWorkflow.__init__`). Only DFT-evaluated structures (with `REF_energy`/`REF_forces`) are stored in it.
+- Initialization config uses individual counts (`num_dimers_per_combo`, `num_trimers_per_combo`, `num_amorphous`, `num_stretch_compress_per_mp`) rather than the old `d_t_s_a_ratio` + `target_non_mp_structures_to_add`.
+- `IsolatedAtom` and `init_MP` config_types are deduplicated by `(config_type, formula)` in `GlobalDatabase.add_structures()`; other config_types (dimers, trimers, amorphous, AL loop structures) are always added without exact dedup.
+- In `initialize_training_set`, the DB is checked **first** (`compute_initialization_needs` against current DB state). `extra_datasets` are seeded only if the DB is still missing some initialization targets, then needs are re-checked before any structure generation. An already-populated DB is always honoured before consulting extra datasets.
+- `initialize_training_set` has two paths: (1) fast path — if `initial_train_file_path` and `initial_test_file_path` exist on disk, load them directly; (2) DB path — call `compute_initialization_needs`, generate only missing structures, run DFT, build train/test from `db.get_all_as_atoms()`.
+- `jobs_dict["high_accuracy_evaluation"]["name"]` must equal `"high_accuracy_evaluation"`. `ase_remote_submitter` always writes output to the hardcoded path `results/<base>/high_accuracy_evaluation/batch_N/`; the result-collection glob in `standard_active_learning.high_accuracy_evaluation` uses `output_name` (i.e. the `name` field) as the subdirectory. If they diverge the glob finds nothing, an empty sentinel is written, and the phase is permanently marked done with zero structures.
+- Guard user config errors in functions that run remotely with `if`/`raise ValueError(...)`, not `assert`. Python's `-O` flag (common in HPC module environments) strips all asserts silently, deferring config failures to the remote job hours after submission.
+- GO (geometry-optimisation) and SP (single-point) QE batches use different numbering ranges to avoid directory collision. `current_batches` = count of existing batch dirs (the directory-name offset). `n_new_batches` = new GO batches needed. GO dirs are numbered `[current_batches, current_batches + n_new_batches)`; SP dirs start at `current_batches + n_new_batches`. The loop index `i` (0-based) is used to slice the trimmed structures list; `batch_num = current_batches + i` is used for the directory name only.
+
+### sage_lib / GlobalDatabase internals
+
+`sage_lib.Partition` (hybrid HDF5+SQLite) only persists `atoms.info`, **not** `atoms.arrays`. `REF_forces` must be serialised into info before storage (`a.info["_REF_forces"] = forces.tolist()`) and restored on retrieval (`np.array(meta.pop("_REF_forces"))`). This is handled transparently by `GlobalDatabase._prepare_for_storage` / `_atoms_from_container`.
+
+`count_all_by_config_type_and_formula()` does a single O(N) scan over all containers and returns `{config_type: {formula: count}}`. Use it instead of calling `count_by_config_type_and_formula()` multiple times.
+
+### Test suite
+
+Tests live in `tests/` with subdirectories mirroring the source layout. New directories added:
+- `tests/database_tests/` — GlobalDatabase dedup and round-trip tests
+- `tests/initialize_tests/` — `compute_initialization_needs` delta logic
+
+All tests are marked `@pytest.mark.unit` **on each individual test method** (run without any external services). Do not apply the mark only at the class level — pytest's mark inheritance is configuration-dependent and `pytest -m unit` may miss class-level-only marks. The suite tests real code paths — no "mock-testing" (asserting that a mock returns what you told it to return).
+
+Key test patterns:
+- `GlobalDatabase` tests use real sage_lib via `GlobalDatabase(str(tmp_path / "db"))` for genuine round-trip verification.
+- `compute_initialization_needs` tests use a `MagicMock` DB that returns controlled `count_all_by_config_type_and_formula()` dicts.
+- `mace` is patched at the top of `test_standard_active_learning.py` via `sys.modules.setdefault(...)` before the module is imported (avoids GPU dependency at collection time).
+- `wfl` is not installed — never patch or import it in tests.