atlas.core.gui.project package

Project management for the ATLAS GUI.

Submodules

atlas.core.gui.project.aiida_sync module

Query AiiDA for process states and sync them into the project DB.

All AiiDA imports are deferred so the module can be imported without AiiDA installed, the functions raise RuntimeError at call time if AiiDA is unavailable.

class atlas.core.gui.project.aiida_sync.SyncResult(al_checked: int = 0, al_updated: int = 0, dft_checked: int = 0, dft_updated: int = 0, errors: list[str] = <factory>)

Bases: object

Summary of what changed during an AiiDA sync.

al_checked: int = 0

al_updated: int = 0

dft_checked: int = 0

dft_updated: int = 0

errors: list[str]

property summary: str

atlas.core.gui.project.aiida_sync.sync_al_runs(project) → SyncResult: Refresh AL run statuses from AiiDA.

atlas.core.gui.project.aiida_sync.sync_all(project) → SyncResult: Sync both AL and DFT runs from AiiDA. Returns combined result.

atlas.core.gui.project.aiida_sync.sync_dft_runs(project) → SyncResult: Refresh DFT run statuses from AiiDA.

atlas.core.gui.project.migrations module

Project schema migrations.

Each migration is a function migrate_v{N}_to_v{N+1}(conn). apply_migrations walks them in order from the project’s current schema_version up to schema.SCHEMA_VERSION.

atlas.core.gui.project.migrations.apply_migrations(conn) → int: Bring the database up to schema.SCHEMA_VERSION. Returns the final version.

atlas.core.gui.project.project module

The Project class, runtime API for an ATLAS GUI project bundle.

Layout

The project bundle consists of an SQLite file and a canonical artifact directory:

<parent>/<name>.atlasproj - SQLite file with index, settings history, summaries
<parent>/<name>.atlas/ - artifact directory containing: - database_generation_settings.toml - active_learning_settings.toml - dft_settings.toml - databases/<database_name>.xz - models/<al_run_id>/... - reports/<al_run_id>/... - logs/<command>.<ts>.log

Configs live at the top of the .atlas/ directory so that CLI tools invoked with that directory as CWD find them via their existing default filename lookups (e.g. cli_active_learning.py looks for active_learning_settings.toml).

class atlas.core.gui.project.project.Project(path: Path, conn: Connection)

Bases: object

In-memory handle for an open ATLAS project.

active_config(section: str) → tuple[int, str] | None: Return (snapshot_id, toml) for the active snapshot of section.

al_run_counts() → dict[str, int]

clear_structures_index() → None: Remove all rows from the structures table.

close() → None

config_path(section: str) → Path

classmethod create(parent_dir: Path | str, name: str) → Project: Create a new project bundle. Raises if it would overwrite existing data.

cwd() → Path: Working directory for CLI subprocesses launched by the GUI.

dft_run_counts() → dict[str, int]

property dir: Path

init_db_name() → str

init_db_path() → Path

latest_al_run_id() → int | None

list_al_iterations(run_id: int) → list[dict]

list_al_runs() → list[dict]

list_config_snapshots(section: str) → list[dict]

list_dft_runs() → list[dict]

list_structures(limit: int | None = None) → list[dict]

log_path(command: str) → Path

meta(key: str, default: str | None = None) → str | None

modifications_breakdown() → list[tuple[str, int]]: Count how many structures have each modification flag.

n_atoms_list() → list[int]: Return all non-null n_atoms values for histogram plotting.

property name: str

classmethod open(atlasproj_path: Path | str) → Project: Open an existing project. Applies any pending migrations.

record_al_submission(base_workchain_pk: int | None, config_snapshot_id: int | None, status: str = 'submitted') → int

record_dft_submission(calc_uuid: str, aiida_pk: int | None, atl_id: str | None, queue: str | None, status: str = 'submitted') → None

refresh_al_run(run_id: int) → None: Query AiiDA for a single AL workchain and update its status.

refresh_dft_runs() → None: Query AiiDA for tracked DFT calculations and update statuses.

refresh_structures_index(force: bool = False) → int

Walk the on-disk initial DB and upsert summary rows. Returns count.

Skips the expensive .xz decompression when the file hasn’t changed since the last successful index (based on mtime). Pass force=True to re-scan unconditionally.

remove_structures_from_index(atl_ids: list[str]) → None: Remove structures from the SQLite index (main-thread only).

save_config_snapshot(section: str, toml_text: str, label: str | None = None, activate: bool = True) → int: Insert a snapshot row; optionally activate it and mirror to disk.

set_meta(key: str, value: str) → None

structure_breakdown(column: str) → list[tuple[str, int]]: Group structures by column and return [(value, count), …].

structure_counts() → dict[str, int]

update_al_run_status(run_id: int, status: str, finished: bool = False) → None

upsert_al_iterations(run_id: int, iterations: list[dict]) → int

Insert or update iteration rows parsed from a log file.

Each dict in iterations should have keys matching al_iterations columns (iteration, db_size, rmse_e, rmse_f, …). Returns the number of rows upserted.

workflow_state() → dict

Return a per-stage workflow status used by the Overview tracker.

Stages: init_db, dft, al, reports. Each carries a status of empty / partial / running / done and a short human-readable metric. next_recommended names the first stage that is not yet done (or None if everything is done).

exception atlas.core.gui.project.project.ProjectError

Bases: Exception

Raised on project create / open / migration failures.

atlas.core.gui.project.recent module

Persistence for the Hub’s “Recent Projects” list.

A small JSON file under the user’s ATLAS config directory. Capped at 10 entries; most-recent-first.

class atlas.core.gui.project.recent.RecentEntry(path: str, name: str, last_opened_at: float)

Bases: object

One row in the Hub’s recent-projects list.

last_opened_at: float

property last_opened_when: str: Human-readable relative time since last open.

name: str

path: str

class atlas.core.gui.project.recent.RecentProjects(path: Path | None = None)

Bases: object

File-backed recent-projects list.

prune_missing() → int: Drop entries whose project file no longer exists. Returns count dropped.

remove(project_path: Path) → None

touch(project_path: Path, project_name: str) → None: Record an open / create of project_path as most recent.

atlas.core.gui.project.schema module

SQLite schema for ATLAS GUI project files.

The DB is a thin index / summary layer over the sibling <project>.atlas/ directory. Heavy data (atom positions, model weights, plot images) is kept on disk; only small queryable fields and pointers live here.

atlas.core.gui.project.schema.initialise(conn) → None: Create every table on a fresh connection.

atlas.core.gui.project.schema.read_schema_version(conn) → int

Module contents

ATLAS GUI project layer.

A Project bundles ATLAS configurations, structure databases, and run summaries into a single addressable unit on disk. See project.py for the runtime API and schema.py for the SQLite schema.

class atlas.core.gui.project.Project(path: Path, conn: Connection)

Bases: object

In-memory handle for an open ATLAS project.

active_config(section: str) → tuple[int, str] | None: Return (snapshot_id, toml) for the active snapshot of section.

al_run_counts() → dict[str, int]

clear_structures_index() → None: Remove all rows from the structures table.

close() → None

config_path(section: str) → Path

classmethod create(parent_dir: Path | str, name: str) → Project: Create a new project bundle. Raises if it would overwrite existing data.

cwd() → Path: Working directory for CLI subprocesses launched by the GUI.

dft_run_counts() → dict[str, int]

property dir: Path

init_db_name() → str

init_db_path() → Path

latest_al_run_id() → int | None

list_al_iterations(run_id: int) → list[dict]

list_al_runs() → list[dict]

list_config_snapshots(section: str) → list[dict]

list_dft_runs() → list[dict]

list_structures(limit: int | None = None) → list[dict]

log_path(command: str) → Path

meta(key: str, default: str | None = None) → str | None

modifications_breakdown() → list[tuple[str, int]]: Count how many structures have each modification flag.

n_atoms_list() → list[int]: Return all non-null n_atoms values for histogram plotting.

property name: str

classmethod open(atlasproj_path: Path | str) → Project: Open an existing project. Applies any pending migrations.

record_al_submission(base_workchain_pk: int | None, config_snapshot_id: int | None, status: str = 'submitted') → int

record_dft_submission(calc_uuid: str, aiida_pk: int | None, atl_id: str | None, queue: str | None, status: str = 'submitted') → None

refresh_al_run(run_id: int) → None: Query AiiDA for a single AL workchain and update its status.

refresh_dft_runs() → None: Query AiiDA for tracked DFT calculations and update statuses.

refresh_structures_index(force: bool = False) → int

Walk the on-disk initial DB and upsert summary rows. Returns count.

Skips the expensive .xz decompression when the file hasn’t changed since the last successful index (based on mtime). Pass force=True to re-scan unconditionally.

remove_structures_from_index(atl_ids: list[str]) → None: Remove structures from the SQLite index (main-thread only).

save_config_snapshot(section: str, toml_text: str, label: str | None = None, activate: bool = True) → int: Insert a snapshot row; optionally activate it and mirror to disk.

set_meta(key: str, value: str) → None

structure_breakdown(column: str) → list[tuple[str, int]]: Group structures by column and return [(value, count), …].

structure_counts() → dict[str, int]

update_al_run_status(run_id: int, status: str, finished: bool = False) → None

upsert_al_iterations(run_id: int, iterations: list[dict]) → int

Insert or update iteration rows parsed from a log file.

Each dict in iterations should have keys matching al_iterations columns (iteration, db_size, rmse_e, rmse_f, …). Returns the number of rows upserted.

workflow_state() → dict

Return a per-stage workflow status used by the Overview tracker.

Stages: init_db, dft, al, reports. Each carries a status of empty / partial / running / done and a short human-readable metric. next_recommended names the first stage that is not yet done (or None if everything is done).

exception atlas.core.gui.project.ProjectError

Bases: Exception

Raised on project create / open / migration failures.

class atlas.core.gui.project.RecentProjects(path: Path | None = None)

Bases: object

File-backed recent-projects list.

prune_missing() → int: Drop entries whose project file no longer exists. Returns count dropped.

remove(project_path: Path) → None

touch(project_path: Path, project_name: str) → None: Record an open / create of project_path as most recent.