nt2gui 0.1.0__tar.gz

nt2gui-0.1.0/.gitignore

@@ -0,0 +1,229 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+node_modules/
+dist/
+
+# devenv
+.devenv*
+devenv.local.nix
+.pre-commit-config.yaml
+
+# nt2gui session state
+.nt2gui/
+
+# Built client, bundled into the Python package
+nt2gui/static/

nt2gui-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: nt2gui
+Version: 0.1.0
+Summary: Browser UI for visualizing Entity simulation output, served from where the data lives.
+Project-URL: Repository, https://github.com/haykh/nt2gui
+Author-email: Hayk Hakobyan <hhakobyan@flatironinstitute.org>
+Requires-Python: >=3.10
+Requires-Dist: flask>=3.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: nt2py[hdf5]>=1.6
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: pydantic>=2.5
+Requires-Dist: waitress>=3.0
+Requires-Dist: xarray>=2024.1
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nt2gui
+
+A browser UI for visualizing [Entity](https://github.com/entity-toolkit/entity) simulation output, read with [nt2py](https://github.com/entity-toolkit/nt2py).
+
+The server runs where the data lives (e.g. a cluster node), does all the data processing, and serves the UI. Your browser connects to it through an SSH tunnel, so nothing needs to be installed on your laptop.
+
+## Usage
+
+On the cluster:
+
+```bash
+python -m venv ~/nt2gui-env
+~/nt2gui-env/bin/pip install nt2gui
+~/nt2gui-env/bin/nt2gui serve            # --port, --host, --state-file, --threads
+```
+
+It prints the tunnel command to run on your machine, e.g.
+
+```bash
+ssh -N -L 8765:localhost:8765 you@node042      # add -J you@login-node if needed
+```
+
+then open <http://localhost:8765/>.
+
+By default the server listens on `127.0.0.1` only. The UI session is saved to `.nt2gui/session.json` in the working directory (override with `--state-file` or `$NT2GUI_STATE_FILE`) and restored on restart.
+
+## Development
+
+```bash
+pip install -r requirements.txt    # or: pip install -e ".[dev]"
+npm i
+npm run dev       # Flask on :5000 and vite with /api proxied to it
+npm run test      # vitest + pytest
+npm run package   # build the client into nt2gui/static, then the wheel/sdist into dist/
+```

nt2gui-0.1.0/README.md

@@ -0,0 +1,35 @@
+# nt2gui
+
+A browser UI for visualizing [Entity](https://github.com/entity-toolkit/entity) simulation output, read with [nt2py](https://github.com/entity-toolkit/nt2py).
+
+The server runs where the data lives (e.g. a cluster node), does all the data processing, and serves the UI. Your browser connects to it through an SSH tunnel, so nothing needs to be installed on your laptop.
+
+## Usage
+
+On the cluster:
+
+```bash
+python -m venv ~/nt2gui-env
+~/nt2gui-env/bin/pip install nt2gui
+~/nt2gui-env/bin/nt2gui serve            # --port, --host, --state-file, --threads
+```
+
+It prints the tunnel command to run on your machine, e.g.
+
+```bash
+ssh -N -L 8765:localhost:8765 you@node042      # add -J you@login-node if needed
+```
+
+then open <http://localhost:8765/>.
+
+By default the server listens on `127.0.0.1` only. The UI session is saved to `.nt2gui/session.json` in the working directory (override with `--state-file` or `$NT2GUI_STATE_FILE`) and restored on restart.
+
+## Development
+
+```bash
+pip install -r requirements.txt    # or: pip install -e ".[dev]"
+npm i
+npm run dev       # Flask on :5000 and vite with /api proxied to it
+npm run test      # vitest + pytest
+npm run package   # build the client into nt2gui/static, then the wheel/sdist into dist/
+```

nt2gui-0.1.0/hatch_build.py

@@ -0,0 +1,17 @@
+"""Refuse to build a wheel without the client, which would serve no UI."""
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        if version == "editable":  # served from the checkout; built on demand
+            return
+        index = Path(self.root) / "nt2gui" / "static" / "index.html"
+        if not index.is_file():
+            raise RuntimeError(
+                f"{index} is missing: run `npm run build` before building the wheel "
+                "(or use `npm run package`)."
+            )

nt2gui-0.1.0/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-0.1.0/nt2gui/__main__.py

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

nt2gui-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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)})