nt2gui 0.1.0__py3-none-any.whl

nt2gui/__init__.py

@@ -0,0 +1,8 @@
+"""nt2gui: a browser UI for Entity (nt2py) simulation output."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("nt2gui")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0+unknown"

nt2gui/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

nt2gui/api/__init__.py

@@ -0,0 +1,12 @@
+"""The JSON API, served under `/api`: one blueprint per area."""
+
+from flask import Blueprint
+
+from . import fields, particles, simulations, state
+
+
+def create_api() -> Blueprint:
+    api = Blueprint("api", __name__)
+    for area in (state, simulations, fields, particles):
+        api.register_blueprint(area.bp)
+    return api

nt2gui/api/common.py

@@ -0,0 +1,69 @@
+"""Request helpers shared by the API blueprints.
+
+Helpers raise `UserError` (400) / `NotFound` (404); the app's error handlers
+turn those, and pydantic `ValidationError`s, into JSON error responses.
+"""
+
+import json
+from typing import Any, TypeVar
+
+import xarray as xr
+from flask import current_app, request
+from pydantic import BaseModel, ValidationError
+
+from ..data.particles import particle_dataset
+from ..errors import UserError
+from ..sources import SimulationSource
+from ..workspace import Workspace
+
+EXTENSION_KEY = "nt2gui.workspace"
+Model = TypeVar("Model", bound=BaseModel)
+
+
+def workspace() -> Workspace:
+    return current_app.extensions[EXTENSION_KEY]
+
+
+def simulation(simulation_id: str) -> SimulationSource:
+    return workspace().simulation(simulation_id)
+
+
+def json_object() -> dict[str, Any]:
+    """The request body, which must be a JSON object (missing counts as {})."""
+    payload = request.get_json(silent=True)
+    if payload is None:
+        return {}
+    if not isinstance(payload, dict):
+        raise UserError("Expected a JSON object")
+    return payload
+
+
+def require_time(payload: dict[str, Any]) -> float:
+    time = payload.get("time")
+    # bool is an int subclass, but never a valid time.
+    if isinstance(time, bool) or not isinstance(time, (int, float)):
+        raise UserError("Time value is required")
+    return float(time)
+
+
+def require_text(payload: dict[str, Any], key: str, message: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise UserError(message)
+    return value.strip()
+
+
+def parse(model: type[Model], value: Any, what: str) -> Model:
+    try:
+        return model.model_validate(value)
+    except ValidationError as error:
+        raise UserError(
+            f"Invalid {what}", details=json.loads(error.json(include_url=False))
+        ) from error
+
+
+def particles_at(source: SimulationSource, time: float) -> tuple[xr.Dataset, float]:
+    """Particles of the output nearest to `time`, and that output's time."""
+    if not source.species:
+        raise UserError("This simulation has no particle output")
+    return particle_dataset(source.particles(time)), source.particle_time(time)

nt2gui/api/fields.py

@@ -0,0 +1,59 @@
+"""Field metadata, custom-quantity checks, and field plots."""
+
+from flask import Blueprint, jsonify
+
+from ..data.metadata import field_metadata
+from ..data.quantities import quantity_dims
+from ..plots.line import render_line
+from ..plots.pseudocolor import render_pseudocolor
+from ..session.schema import LineConfig, PseudocolorConfig, Range, ZoomWindow
+from .common import json_object, parse, require_text, require_time, simulation
+
+bp = Blueprint("fields", __name__, url_prefix="/simulations/<simulation_id>")
+
+
+@bp.get("/fields")
+def get_fields(simulation_id: str):
+    return jsonify(field_metadata(simulation(simulation_id).fields))
+
+
+@bp.post("/quantities/check")
+def check_quantity(simulation_id: str):
+    """Validate a field name or expression and report its spatial dims."""
+    source = simulation(simulation_id)
+    expression = require_text(json_object(), "expression", "An expression is required")
+    dims = quantity_dims(expression, source.fields)
+    return jsonify({"expression": expression, "dims": dims})
+
+
+@bp.post("/render/line")
+def line_plot(simulation_id: str):
+    source = simulation(simulation_id)
+    payload = json_object()
+    time = require_time(payload)
+    config = parse(LineConfig, payload.get("config"), "line plot request")
+    value_range = (
+        parse(Range, payload["range"], "zoom range").to_wire()
+        if payload.get("range") is not None
+        else None
+    )
+    fields = source.fields
+    return jsonify(
+        render_line(
+            fields, config.quantities, config.axis, config.slices, time, value_range
+        )
+    )
+
+
+@bp.post("/render/pseudocolor")
+def pseudocolor_plot(simulation_id: str):
+    source = simulation(simulation_id)
+    payload = json_object()
+    time = require_time(payload)
+    config = parse(PseudocolorConfig, payload.get("config"), "pseudocolor request")
+    viewport = (
+        parse(ZoomWindow, payload["viewport"], "zoom window")
+        if payload.get("viewport") is not None
+        else None
+    )
+    return jsonify(render_pseudocolor(source.fields, config, time, viewport))

nt2gui/api/particles.py

@@ -0,0 +1,62 @@
+"""Particle metadata, custom-quantity checks, and particle plots."""
+
+from flask import Blueprint, jsonify
+
+from ..data.metadata import particle_metadata
+from ..data.particles import particle_dataset, quantity_values
+from ..errors import UserError
+from ..plots.particle_histogram import render_particle_histogram
+from ..plots.particle_phase import render_particle_phase
+from ..session.schema import ParticleHistogramConfig, ParticlePhaseConfig
+from ..sources import first_particles
+from .common import (
+    json_object,
+    parse,
+    particles_at,
+    require_text,
+    require_time,
+    simulation,
+)
+
+bp = Blueprint("particles", __name__, url_prefix="/simulations/<simulation_id>")
+
+# Expressions are checked on a few particles; validity doesn't depend on values.
+CHECK_SAMPLE_SIZE = 16
+
+
+@bp.get("/particles")
+def get_particles(simulation_id: str):
+    return jsonify(particle_metadata(simulation(simulation_id)))
+
+
+@bp.post("/particles/check")
+def check_particle_quantity(simulation_id: str):
+    source = simulation(simulation_id)
+    expression = require_text(json_object(), "expression", "An expression is required")
+    if not source.species:
+        raise UserError("This simulation has no particle output")
+    sample = particle_dataset(first_particles(source).head(CHECK_SAMPLE_SIZE))
+    quantity_values(expression, sample)
+    return jsonify({"expression": expression})
+
+
+@bp.post("/render/particles/histogram")
+def histogram_plot(simulation_id: str):
+    source = simulation(simulation_id)
+    payload = json_object()
+    time = require_time(payload)
+    config = parse(ParticleHistogramConfig, payload.get("config"), "histogram request")
+    particles, timestamp = particles_at(source, time)
+    return jsonify(
+        {**render_particle_histogram(particles, config), "timestamp": timestamp}
+    )
+
+
+@bp.post("/render/particles/phase")
+def phase_plot(simulation_id: str):
+    source = simulation(simulation_id)
+    payload = json_object()
+    time = require_time(payload)
+    config = parse(ParticlePhaseConfig, payload.get("config"), "phase-space request")
+    particles, timestamp = particles_at(source, time)
+    return jsonify({**render_particle_phase(particles, config), "timestamp": timestamp})

nt2gui/api/simulations.py

@@ -0,0 +1,24 @@
+"""Opening and closing simulations, and what each contains."""
+
+from flask import Blueprint, jsonify
+
+from ..data.metadata import summarize
+from .common import json_object, require_text, simulation, workspace
+
+bp = Blueprint("simulations", __name__)
+
+
+@bp.post("/simulations")
+def add_simulation():
+    path = require_text(json_object(), "path", "Simulation path is required")
+    return jsonify(workspace().add(path))
+
+
+@bp.delete("/simulations/<simulation_id>")
+def remove_simulation(simulation_id: str):
+    return jsonify(workspace().remove(simulation_id))
+
+
+@bp.get("/simulations/<simulation_id>/summary")
+def get_summary(simulation_id: str):
+    return jsonify(summarize(simulation(simulation_id)))

nt2gui/api/state.py

@@ -0,0 +1,79 @@
+"""The synced UI state, and saving/loading whole sessions."""
+
+from flask import Blueprint, current_app, jsonify
+
+from ..errors import Conflict, NotFound, UserError
+from ..session.files import (
+    parse_document,
+    read_document,
+    resolve_session_path,
+    write_document,
+)
+from ..session.schema import UiState
+from .common import json_object, parse, require_text, workspace
+
+bp = Blueprint("state", __name__)
+
+
+@bp.get("/state")
+def get_state():
+    return jsonify(workspace().store.snapshot())
+
+
+@bp.put("/state")
+def put_state():
+    payload = json_object()
+    revision = payload.get("revision")
+    if isinstance(revision, bool) or not isinstance(revision, int):
+        raise UserError("Expected {revision: int, state: object}")
+    state = parse(UiState, payload.get("state"), "state")
+    return jsonify(workspace().store.replace_state(state, revision))
+
+
+@bp.get("/session/export")
+def export_session():
+    return jsonify(workspace().store.document().to_wire())
+
+
+@bp.post("/session/import")
+def import_session():
+    try:
+        document = parse_document(json_object().get("session"))
+    except ValueError as error:
+        raise UserError(f"Invalid session file: {error}") from error
+    return jsonify(workspace().apply_document(document))
+
+
+@bp.post("/session/save")
+def save_session():
+    payload = json_object()
+    path = resolve_session_path(
+        require_text(payload, "path", "A session file path is required")
+    )
+    try:
+        write_document(
+            path, workspace().store.document(), bool(payload.get("overwrite"))
+        )
+    except FileExistsError as error:
+        raise Conflict("File already exists", path=str(path)) from error
+    except OSError as error:
+        raise UserError(f"Could not write {path}: {error.strerror or error}") from error
+    current_app.logger.info("Session saved to %s", path)
+    return jsonify({**workspace().store.snapshot(), "path": str(path)})
+
+
+@bp.post("/session/load")
+def load_session():
+    path = resolve_session_path(
+        require_text(json_object(), "path", "A session file path is required")
+    )
+    try:
+        document = read_document(path)
+    except FileNotFoundError as error:
+        raise NotFound("File not found", path=str(path)) from error
+    except ValueError as error:
+        raise UserError(f"Invalid session file: {error}") from error
+    except OSError as error:
+        raise UserError(f"Could not read file: {error.strerror or error}") from error
+    current_app.logger.info("Session loaded from %s", path)
+    return jsonify({**workspace().apply_document(document), "path": str(path)})

nt2gui/app.py

@@ -0,0 +1,51 @@
+"""The Flask app: the JSON API under `/api` and the built client at `/`."""
+
+import logging
+from pathlib import Path
+
+from flask import Flask, jsonify, send_from_directory
+
+from . import config
+from .api import create_api
+from .api.common import EXTENSION_KEY
+from .errors import UserError
+from .session.store import SessionStore
+from .workspace import Workspace
+
+
+def create_app(
+    state_file: Path | str | None = None, static_dir: Path | str | None = None
+) -> Flask:
+    """`state_file` defaults to $NT2GUI_STATE_FILE, then `.nt2gui/session.json`
+    in the working directory; `static_dir` defaults to the bundled client."""
+    app = Flask(__name__, static_folder=None)
+    app.logger.setLevel(logging.INFO)
+
+    path = config.state_file(state_file)
+    app.logger.info("Session file: %s", path.resolve())
+    app.extensions[EXTENSION_KEY] = Workspace(SessionStore(path))
+
+    @app.errorhandler(UserError)
+    def user_error(error: UserError):
+        return jsonify({"error": error.message, **error.extra}), error.status
+
+    app.register_blueprint(create_api(), url_prefix="/api")
+    _serve_client(app, Path(static_dir) if static_dir else config.STATIC_DIR)
+    return app
+
+
+def _serve_client(app: Flask, static_dir: Path) -> None:
+    """Serve the single-page client. Asset URLs are relative (vite `base: "./"`)
+    so the app also works behind a path-prefixing proxy."""
+
+    @app.get("/")
+    @app.get("/<path:filename>")
+    def client(filename: str = "index.html"):
+        if not (static_dir / "index.html").is_file():
+            return (
+                "The nt2gui client is not built. Run `npm run build`, or use "
+                "`npm run dev` for development.",
+                404,
+                {"Content-Type": "text/plain; charset=utf-8"},
+            )
+        return send_from_directory(static_dir, filename)

nt2gui/cli.py

@@ -0,0 +1,108 @@
+"""`nt2gui serve`: run the server (API and bundled client) on this machine.
+
+The server is meant to run next to the data (e.g. on a cluster node) while the
+browser runs on the user's laptop, connected through an SSH tunnel.
+"""
+
+import argparse
+import getpass
+import logging
+import socket
+import sys
+from pathlib import Path
+
+from . import __version__, config
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+
+def tunnel_hint(port: int, host: str, hostname: str, user: str) -> str:
+    """How to reach a server on `hostname:port` from the user's machine."""
+    if host in ("127.0.0.1", "localhost", "::1"):
+        # Loopback is reachable only from `hostname` itself, so tunnel to it.
+        command = f"ssh -N -L {port}:localhost:{port} {user}@{hostname}"
+        note = f"(add `-J {user}@<login-node>` if {hostname} is behind a login node)"
+    else:
+        command = f"ssh -N -L {port}:{hostname}:{port} {user}@<login-node>"
+        note = ""
+    lines = [
+        f"nt2gui {__version__} serving on {hostname}:{port}",
+        "From your machine, open a tunnel:",
+        f"    {command}",
+        *([f"    {note}"] if note else []),
+        f"then browse to http://localhost:{port}/",
+    ]
+    return "\n".join(lines)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nt2gui", description=__doc__)
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    serve = commands.add_parser("serve", help="Run the nt2gui server.")
+    serve.add_argument(
+        "--host",
+        default=DEFAULT_HOST,
+        help=f"Interface to bind (default: {DEFAULT_HOST}, reachable only "
+        "from this machine; use an SSH tunnel).",
+    )
+    serve.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        help=f"Port to listen on (default: {DEFAULT_PORT}; 0 picks a free one).",
+    )
+    serve.add_argument(
+        "--state-file",
+        type=Path,
+        default=None,
+        help=f"Where the UI session is persisted (default: ${config.STATE_FILE_ENV} "
+        f"or {config.DEFAULT_STATE_FILE}).",
+    )
+    serve.add_argument(
+        "--threads",
+        type=int,
+        default=8,
+        help="Worker threads for concurrent requests (default: 8).",
+    )
+    return parser
+
+
+def serve(host: str, port: int, state_file: Path | None, threads: int) -> None:
+    # Imported here so `nt2gui --help` stays fast.
+    from waitress import create_server
+
+    from .app import create_app
+
+    logging.basicConfig(
+        level=logging.INFO, format="%(levelname)s %(name)s: %(message)s"
+    )
+    # One process on purpose: open simulations, caches and the session live in
+    # memory and must be shared by all requests.
+    server = create_server(
+        create_app(state_file), host=host, port=port, threads=threads
+    )
+    effective_port = getattr(server, "effective_port", port)
+    print(
+        tunnel_hint(effective_port, host, socket.gethostname(), getpass.getuser()),
+        flush=True,
+    )
+    try:
+        server.run()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "serve":
+        serve(args.host, args.port, args.state_file, args.threads)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nt2gui/config.py

@@ -0,0 +1,14 @@
+"""Defaults and environment settings shared by the app and the CLI."""
+
+import os
+from pathlib import Path
+
+STATE_FILE_ENV = "NT2GUI_STATE_FILE"
+DEFAULT_STATE_FILE = Path(".nt2gui") / "session.json"
+# The built client (`npm run build`), bundled into the wheel as package data.
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+
+
+def state_file(explicit: Path | str | None = None) -> Path:
+    """The session file: `explicit`, else $NT2GUI_STATE_FILE, else the default."""
+    return Path(explicit or os.environ.get(STATE_FILE_ENV, DEFAULT_STATE_FILE))

nt2gui/data/arrays.py

@@ -0,0 +1,9 @@
+"""Array helpers for JSON responses."""
+
+import numpy as np
+
+
+def finite_list(values: object) -> list[float | None]:
+    """Floats for JSON, with NaN/inf (not valid JSON) as null."""
+    array = np.asarray(values, dtype=float).ravel()
+    return [float(v) if np.isfinite(v) else None for v in array]