Atlas Integration

Overview

Atlas (Nomosis) is an external service for cloud-based molecular structure storage and computation. codemol integrates with Atlas through a three-layer architecture:

graph LR
    A[AtlasManager] -->|creates| B[AtlasWorker]
    B -->|uses| C[AtlasClient]
    C -->|HTTP| D[Atlas API]
    B -->|signals| A
    A -->|updates| E[Console / UI]

The Three Layers

AtlasClient (codemol/atlas_client.py)

Low-level HTTP client. Handles authentication, request formatting, and response parsing:

class AtlasClient:
    def __init__(self, api_key: str, base_url: str): ...
    def fetch_structure(self, structure_id: str) -> dict: ...
    def save_session(self, session_data: dict) -> str: ...
    def list_sessions(self) -> list[dict]: ...

AtlasWorker (codemol/atlas_worker.py)

QThread worker that wraps AtlasClient calls for async execution:

class AtlasWorker(QThread):
    finished = pyqtSignal(object)
    error = pyqtSignal(str)

    def __init__(self, client, operation, **kwargs): ...
    def run(self): ...

AtlasManager (codemol/app/atlas_manager.py)

Manager that connects the worker to the UI. Handles lifecycle, signal connections, and state management:

class AtlasManager:
    def __init__(self, ctx: AppContext): ...
    def fetch_structure(self, structure_id): ...
    def save_current_session(self): ...
    def _on_fetch_complete(self, result): ...
    def _on_error(self, message): ...

Data Flow Example

sequenceDiagram
    participant User
    participant Manager as AtlasManager
    participant Worker as AtlasWorker
    participant Client as AtlasClient
    participant API as Atlas API

    User->>Manager: /atlas fetch ABC123
    Manager->>Worker: AtlasWorker(client, "fetch", id="ABC123")
    Manager->>Manager: console.log("Fetching...")
    Worker->>Client: client.fetch_structure("ABC123")
    Client->>API: GET /structures/ABC123
    API-->>Client: {pdb_data: "..."}
    Client-->>Worker: result dict
    Worker-->>Manager: finished.emit(result)
    Manager->>Manager: Load structure into viewer
    Manager->>Manager: console.log("Loaded ABC123")

Session Persistence

Atlas can store codemol sessions (loaded structures, measurements, representations) for cloud backup:

# Save
atlas_mgr.save_current_session()

# Load
atlas_mgr.load_session(session_id)

The session data includes: - Loaded structure IDs - Representation state - Measurements - Camera position - Color schemes