pyatomsk 0.3.0__tar.gz

pyatomsk-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodolfo Herrera Hernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyatomsk-0.3.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: pyatomsk
+Version: 0.3.0
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: voltsdk>=3.0.0
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python

pyatomsk-0.3.0/README.md

@@ -0,0 +1,149 @@
+# Python wrapper for Atomsk
+
+## Install
+
+```bash
+pip install pyatomsk
+```
+
+## Quick start
+
+```python
+from pathlib import Path
+from pyatomsk import AtomicStructure, CubicLattices, DislocationBuilder, DislocationLoop, PluginHub, view
+
+REGISTRY = 'https://raw.githubusercontent.com/VoltLabs-Research/Volt/main/server/static/plugin-registry'
+OUT = Path('output/fcc-dxa')
+
+hub = PluginHub(url=REGISTRY, default_publisher='voltlabs')
+ptm = hub.get('polyhedral-template-matching')
+dxa = hub.get('opendxa')
+
+# 1. Build an FCC Al slab with a prismatic dislocation loop.
+structure = AtomicStructure(
+    lattice=CubicLattices.FCC,
+    lattice_params=[4.06],
+    species=['Al'],
+    orient=['[110]', '[1-12]', '[-111]'],
+    duplicate=[60, 40, 20],
+)
+loop = DislocationLoop(x='0.501*box', y='0.501*box', z='0.501*box',
+                       normal='Z', radius=30, burgers=[2.860954, 0, 0], poisson=0.33)
+builder = DislocationBuilder(atomic_structure=structure, output_file='Al_loop.lmp', dislocations=[loop])
+lmp = builder.run()                      # downloads Atomsk if needed, returns the output Path
+
+# 2. Run the analysis plugins locally.
+ptm_run = ptm(lmp, output_dir=OUT, crystal_structure='fcc', rmsd=0.1)
+dxa_run = dxa(ptm_run, output_dir=OUT, reference_topology='fcc', export_as='json')
+
+# 3. Inspect results as a DataFrame, then view them in VOLT.
+print(dxa_run['dislocations.json'].df())
+view(ptm_run['atoms.msgpack'], output_path=OUT / 'ptm_atoms.glb')
+view(dxa_run['dislocations.json'])
+```
+
+
+## Building structures
+
+`AtomicStructure` maps directly onto `atomsk --create`. You can inspect the command
+before running it:
+
+```python
+from pyatomsk import AtomicStructure, CubicLattices
+
+s = AtomicStructure(
+    lattice=CubicLattices.FCC,
+    lattice_params=[4.05],          # a (and c for tetragonal/hexagonal)
+    species=['Al'],
+    duplicate=[10, 10, 10],
+    export_filename='al.xsf',
+    formats=['xsf'],
+)
+s.to_command()   # 'atomsk --create fcc 4.05 Al -duplicate 10 10 10 al.xsf xsf'
+s.run()          # executes it, returns Path('al.xsf')
+```
+
+Lattice enums: `CubicLattices` (FCC, BCC, SC, diamond, …), `TetragonalLattices`
+(BCT, FCT, ST, L1_0) and `HexagonalLattices` (HCP, graphite, …).
+
+For non-standard cells, `CustomAtomicStructure` writes an XSF seed from an explicit
+`cell` + fractional `basis` and feeds it to Atomsk.
+
+## Adding dislocations
+
+`DislocationBuilder` prepends a structure command and appends one or more
+`-dislocation` fragments:
+
+```python
+from pyatomsk import AtomicStructure, TetragonalLattices, Dislocation, DislocationCharacter, DislocationBuilder
+
+structure = AtomicStructure(lattice=TetragonalLattices.BCT, lattice_params=[2.86, 2.95],
+                            species=['Fe'], duplicate=[32, 32, 24])
+edge = Dislocation(character=DislocationCharacter.EDGE_ADD, p1='0.501*box', p2='0.501*box',
+                   line='z', plane='y', burgers=[2.86], poisson=0.29)
+
+builder = DislocationBuilder(atomic_structure=structure, output_file='bct.lmp', dislocations=[edge])
+builder.run()
+```
+
+Use `DislocationLoop` for prismatic loops (`-dislocation loop …`). Both are pure
+command fragments; only `DislocationBuilder` (and the structures) are runnable.
+
+
+## Running VOLT plugins 
+
+Plugins are fetched from a VOLT plugin registry and executed as local subprocesses by
+voltsdk. A `PluginRun` exposes its outputs as artifacts you
+can look up by name (fuzzy: `.json` ⇄ `.msgpack`, prefixes stripped):
+
+```python
+run = ptm(lmp, output_dir='out', crystal_structure='fcc', rmsd=0.1)
+run['annotated.dump']          # PluginArtifact (os.PathLike)
+run['clusters.table'].df()     # pandas DataFrame
+run['atoms.msgpack'].json()    # parsed payload
+```
+
+OpenDXA auto-wires from a previous run: `dxa(ptm_run, reference_topology='fcc')` pulls the
+annotated dump and cluster tables automatically. After a `pattern-structure-matching` run,
+`dxa(psm_run)` also infers `reference_topology` and `lattice_dir` from the run's lattices.
+
+## Viewing in VOLT
+
+`view()` converts an artifact (or a path / list of them) to GLB, the exporter is detected
+from the payload, and opens it in the VOLT canvas via a local server. GLB files pass
+through untouched.
+
+```python
+view(dxa_run['dislocations.json'])                              # opens in VOLT
+view(ptm_run['atoms.msgpack'], output_path='atoms.glb')         # also keep the GLB
+view(dxa_run['defect_mesh.json'], exporter='MeshExporter')      # force a specific layer
+```
+
+`view()` returns the viewer URL. Equivalent low-level voltsdk calls are re-exported too:
+`PluginArtifact.glb()`, `PluginArtifact.open_in_volt()`, and `open_in_volt(path)`.
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `ATOMSK_BIN` | Path to an existing Atomsk executable (skips auto-download). |
+| `XDG_CACHE_HOME` | Cache root; Atomsk under `<cache>/pyatomsk`, plugins under `<cache>/volt`. |
+| `VOLT_PLUGIN_REGISTRY` | Override the plugin registry URL. |
+| `VOLT_CACHE_DIR` | Override the voltsdk (plugin) cache directory. |
+| `VOLT_APP_URL` | VOLT app URL used by the viewer. |
+
+## API reference
+
+| Symbol | Description |
+|---|---|
+| `AtomicStructure`, `CustomAtomicStructure` | Build a crystal via `atomsk --create` / an XSF seed. |
+| `CubicLattices`, `TetragonalLattices`, `HexagonalLattices` | Lattice type enums. |
+| `Dislocation`, `DislocationLoop` | `-dislocation` command fragments. |
+| `DislocationBuilder` | Combine a structure with one or more dislocations. |
+| `AtomskCommand` | Base class: `.argv()`, `.to_command()`, `.run() -> Path`. |
+| `view(source, *, output_path=None, …)` | Open an artifact/GLB/list in the VOLT canvas. |
+| `PluginHub`, `Plugin`, `PluginRun`, `PluginArtifact`, `Lattice`, `SpatialAssembler`, `open_in_volt` | Re-exported from voltsdk. |
+
+## License
+
+See the repository for license details.

pyatomsk-0.3.0/pyatomsk/__init__.py

@@ -0,0 +1,58 @@
+"""Build Atomsk structures/dislocations, run plugins locally, and view results in VOLT.
+
+Plugin compute runs on your machine via :mod:`voltsdk`; visualization is delegated to the
+VOLT canvas (``view`` / ``open_in_volt``). pyatomsk's own surface is just the Atomsk command
+builders plus a thin viewer helper.
+"""
+
+from voltsdk import (
+    Lattice,
+    Plugin,
+    PluginArtifact,
+    PluginError,
+    PluginHub,
+    PluginRun,
+    SpatialAssembler,
+    open_in_volt,
+)
+
+from pyatomsk.commands import AtomskCommand
+from pyatomsk.dislocations import (
+    Dislocation,
+    DislocationBuilder,
+    DislocationCharacter,
+    DislocationLoop,
+)
+from pyatomsk.structures import (
+    AtomicStructure,
+    CubicLattices,
+    CustomAtomicStructure,
+    HexagonalLattices,
+    TetragonalLattices,
+)
+from pyatomsk.view import view
+
+__all__ = [
+    # voltsdk re-exports (local compute, VOLT viewing)
+    'PluginHub',
+    'Plugin',
+    'PluginArtifact',
+    'PluginRun',
+    'PluginError',
+    'Lattice',
+    'SpatialAssembler',
+    'open_in_volt',
+    # Atomsk command builders
+    'AtomskCommand',
+    'AtomicStructure',
+    'CustomAtomicStructure',
+    'CubicLattices',
+    'TetragonalLattices',
+    'HexagonalLattices',
+    'Dislocation',
+    'DislocationCharacter',
+    'DislocationLoop',
+    'DislocationBuilder',
+    # thin viewer helper
+    'view',
+]

pyatomsk-0.3.0/pyatomsk/atomsk.py

@@ -0,0 +1,93 @@
+"""Resolve the Atomsk executable, downloading the official binary if needed."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import tarfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+ATOMSK_VERSION = 'b0.13.1'
+_BASE_URL = 'https://atomsk.univ-lille.fr/code'
+
+# (system, machine) -> (archive filename, executable name)
+_BINARIES = {
+    ('linux', 'x86_64'): (f'atomsk_{ATOMSK_VERSION}_Linux-amd64.tar.gz', 'atomsk'),
+    ('linux', 'amd64'): (f'atomsk_{ATOMSK_VERSION}_Linux-amd64.tar.gz', 'atomsk'),
+    ('linux', 'i686'): (f'atomsk_{ATOMSK_VERSION}_Linux-i686.tar.gz', 'atomsk'),
+    ('linux', 'i386'): (f'atomsk_{ATOMSK_VERSION}_Linux-i686.tar.gz', 'atomsk'),
+    ('windows', 'amd64'): (f'atomsk_{ATOMSK_VERSION}_Windows.zip', 'atomsk.exe'),
+    ('windows', 'x86_64'): (f'atomsk_{ATOMSK_VERSION}_Windows.zip', 'atomsk.exe'),
+}
+
+
+def _cache_dir() -> Path:
+    base = os.environ.get('XDG_CACHE_HOME') or str(Path.home() / '.cache')
+    return Path(base) / 'pyatomsk'
+
+
+def _extract(archive: Path, target: Path) -> None:
+    if archive.name.endswith('.tar.gz'):
+        with tarfile.open(archive, 'r:gz') as tar:
+            tar.extractall(target)
+    elif archive.suffix == '.zip':
+        with zipfile.ZipFile(archive) as zf:
+            zf.extractall(target)
+    else:
+        raise ValueError(f'Unsupported Atomsk archive: {archive.name}')
+
+
+def ensure_atomsk(*, version: str = ATOMSK_VERSION, force: bool = False) -> Path:
+    """Return the Atomsk executable for this OS, downloading and caching it if needed.
+
+    Resolution order: ``$ATOMSK_BIN`` -> ``atomsk`` on PATH -> cached download ->
+    download the official binary. Only Linux and Windows on x86 have official static
+    binaries; elsewhere (macOS, ARM) install Atomsk yourself (e.g.
+    ``conda install -c conda-forge atomsk``) and point ``ATOMSK_BIN`` at it or add it
+    to PATH.
+    """
+    override = os.environ.get('ATOMSK_BIN')
+    if override:
+        return Path(override).expanduser()
+
+    if not force:
+        on_path = shutil.which('atomsk')
+        if on_path:
+            return Path(on_path)
+
+    system, machine = platform.system().lower(), platform.machine().lower()
+    entry = _BINARIES.get((system, machine))
+    if entry is None:
+        raise RuntimeError(
+            f'No prebuilt Atomsk binary for {system}-{machine}. Install it '
+            '(e.g. `conda install -c conda-forge atomsk`), add it to PATH, or set '
+            'ATOMSK_BIN to its location. See https://atomsk.univ-lille.fr/dl.php'
+        )
+
+    filename, exe = entry
+    install_dir = _cache_dir() / 'atomsk' / version / f'{system}-{machine}'
+    if install_dir.is_dir() and not force:
+        cached = next(install_dir.rglob(exe), None)
+        if cached is not None:
+            return cached
+
+    downloads = _cache_dir() / 'downloads'
+    downloads.mkdir(parents=True, exist_ok=True)
+    archive = downloads / filename
+    if not archive.is_file() or force:
+        with urllib.request.urlopen(f'{_BASE_URL}/{filename}') as response, archive.open('wb') as out:
+            shutil.copyfileobj(response, out)
+
+    if install_dir.exists():
+        shutil.rmtree(install_dir)
+    install_dir.mkdir(parents=True, exist_ok=True)
+    _extract(archive, install_dir)
+
+    binary = next(install_dir.rglob(exe), None)
+    if binary is None:
+        raise RuntimeError(f'{exe!r} not found inside the downloaded Atomsk archive {filename!r}.')
+    binary.chmod(binary.stat().st_mode | 0o111)
+    return binary

pyatomsk-0.3.0/pyatomsk/commands.py

@@ -0,0 +1,51 @@
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+def _prepare_output_path(path: str | Path) -> Path:
+    target = Path(path).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists():
+        if target.is_dir():
+            raise IsADirectoryError(f'Expected a file output path, got directory: {target}')
+        target.unlink()
+    return target
+
+
+class AtomskCommand:
+    """Base for objects that generate (and run) an ``atomsk`` command."""
+
+    def argv(self) -> list[str]:
+        raise NotImplementedError
+
+    def to_command(self) -> str:
+        return shlex.join(self.argv())
+
+    def prepare_run(self) -> None:
+        """Hook for filesystem prep (seed files, output paths). Default: no-op."""
+
+    def output_path(self) -> Path | None:
+        """Path the command writes, or ``None`` if it only prints to stdout."""
+        return None
+
+    def run(
+        self,
+        *,
+        atomsk_output: bool = False,
+        check: bool = True,
+        text: bool = True,
+        **kwargs: Any,
+    ) -> Path | None:
+        from pyatomsk.atomsk import ensure_atomsk
+
+        run_kwargs = dict(kwargs)
+        if not atomsk_output:
+            run_kwargs.setdefault('stdout', subprocess.PIPE)
+            run_kwargs.setdefault('stderr', subprocess.PIPE)
+        self.prepare_run()
+        argv = self.argv()
+        argv[0] = str(ensure_atomsk())
+        subprocess.run(argv, check=check, text=text, **run_kwargs)
+        return self.output_path()

pyatomsk-0.3.0/pyatomsk/dislocations.py

@@ -0,0 +1,117 @@
+import shlex
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Sequence, Union
+
+from pyatomsk.commands import AtomskCommand, _prepare_output_path
+
+Coord = Union[int, float, str]
+Burgers = Union[float, Sequence[float]]
+
+
+class DislocationCharacter(Enum):
+    EDGE = 'edge'
+    EDGE_ADD = 'edge_add'
+    EDGE_RM = 'edge_rm'
+    SCREW = 'screw'
+    MIXED = 'mixed'
+    LOOP = 'loop'
+
+
+def _burgers_args(burgers: Burgers) -> list[Coord]:
+    if isinstance(burgers, Sequence) and not isinstance(burgers, (str, bytes)):
+        return list(burgers)
+    return [burgers]
+
+
+class DislocationSpec:
+    """An ``-dislocation ...`` argv fragment (not a standalone command)."""
+
+    def argv(self) -> list[str]:
+        raise NotImplementedError
+
+    def to_command(self) -> str:
+        return shlex.join(self.argv())
+
+
+@dataclass
+class Dislocation(DislocationSpec):
+    character: DislocationCharacter
+    p1: Coord
+    p2: Coord
+    line: str
+    plane: str
+    burgers: Burgers
+    poisson: float | None = None
+
+    def argv(self) -> list[str]:
+        args = [
+            '-dislocation',
+            self.p1,
+            self.p2,
+            self.character.value,
+            self.line,
+            self.plane,
+            *_burgers_args(self.burgers),
+        ]
+        if self.poisson is not None:
+            args.append(self.poisson)
+        return [str(arg) for arg in args]
+
+
+@dataclass
+class DislocationLoop(DislocationSpec):
+    x: Coord
+    y: Coord
+    z: Coord
+    normal: str
+    radius: float
+    burgers: Sequence[float]
+    poisson: float
+
+    def argv(self) -> list[str]:
+        args = [
+            '-dislocation',
+            'loop',
+            self.x,
+            self.y,
+            self.z,
+            self.normal,
+            self.radius,
+            *self.burgers,
+            self.poisson,
+        ]
+        return [str(arg) for arg in args]
+
+
+@dataclass
+class DislocationBuilder(AtomskCommand):
+    atomic_structure: AtomskCommand
+    output_file: str | None = None
+    formats: Sequence[str] = ()
+    dislocations: list[DislocationSpec] = field(default_factory=list)
+    options: list[str] = field(default_factory=list)
+
+    def argv(self) -> list[str]:
+        command = list(self.atomic_structure.argv(include_export=self.output_file is None))
+
+        for dislocation in self.dislocations:
+            command.extend(dislocation.argv())
+
+        if self.options:
+            command.extend(self.options)
+
+        if self.output_file:
+            command.append(self.output_file)
+            command.extend(self.formats)
+
+        return command
+
+    def output_path(self) -> Path | None:
+        return Path(self.output_file) if self.output_file else None
+
+    def prepare_run(self) -> None:
+        self.atomic_structure.prepare_run()
+        if self.output_file:
+            _prepare_output_path(self.output_file)

pyatomsk-0.3.0/pyatomsk/structures.py

@@ -0,0 +1,130 @@
+import shlex
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Sequence, Union
+
+from pyatomsk.commands import AtomskCommand, _prepare_output_path
+
+
+class CubicLattices(Enum):
+    SC = 'sc'
+    BCC = 'bcc'
+    CsCl = 'CsCl'
+    FCC = 'fcc'
+    L12 = 'L12'
+    FLUORITE = 'fluorite'
+    DIAMOND = 'diamond'
+    ZINCBLENDE = 'zb'
+    ROCKSALT = 'rocksalt'
+    PEROVSKITE = 'per'
+    A15 = 'a15'
+    C15 = 'c15'
+
+
+class TetragonalLattices(Enum):
+    ST = 'st'
+    BCT = 'bct'
+    FCT = 'fct'
+    L10 = 'L1_0'
+
+
+class HexagonalLattices(Enum):
+    HCP = 'hcp'
+    WURTZITE = 'wz'
+    GRAPHITE = 'graphite'
+    BN = 'BN'
+    B12 = 'B12'
+    C14 = 'C14'
+    C36 = 'C36'
+
+
+Lattices = Union[CubicLattices, TetragonalLattices, HexagonalLattices]
+MillerIndex = Union[str, Sequence[int]]
+
+
+def _miller(index: MillerIndex) -> str:
+    if isinstance(index, str):
+        return index
+    return '[' + ''.join(map(str, index)) + ']'
+
+
+@dataclass
+class AtomicStructure(AtomskCommand):
+    lattice: Lattices
+    lattice_params: Sequence[float]
+    species: Sequence[str]
+    orient: Sequence[MillerIndex] | None = None
+    duplicate: Sequence[int] | None = None
+    export_filename: str | None = None
+    formats: Sequence[str] = ()
+
+    def argv(self, *, include_export: bool = True) -> list[str]:
+        args = ['atomsk', '--create', self.lattice.value]
+        args.extend(map(str, self.lattice_params))
+        args.extend(self.species)
+
+        if self.orient is not None:
+            args.append('orient')
+            args.extend(_miller(index) for index in self.orient)
+
+        if self.duplicate is not None:
+            args.append('-duplicate')
+            args.extend(map(str, self.duplicate))
+
+        if include_export and self.export_filename:
+            args.append(self.export_filename)
+            args.extend(self.formats)
+
+        return args
+
+    def to_command(self, *, include_export: bool = True) -> str:
+        return shlex.join(self.argv(include_export=include_export))
+
+    def output_path(self) -> Path | None:
+        return Path(self.export_filename) if self.export_filename else None
+
+    def prepare_run(self) -> None:
+        if self.export_filename:
+            _prepare_output_path(self.export_filename)
+
+
+@dataclass
+class CustomAtomicStructure(AtomskCommand):
+    cell: Sequence[Sequence[float]]
+    basis: Sequence[tuple[str, Sequence[float]]]
+    duplicate: Sequence[int] | None = None
+    seed_filename: str = 'cementite_unitcell.xsf'
+
+    def _seed_text(self) -> str:
+        lines = [
+            'CRYSTAL',
+            'PRIMVEC',
+            *[f'{v[0]} {v[1]} {v[2]}' for v in self.cell],
+            'PRIMCOORD',
+            f'{len(self.basis)} 1',
+        ]
+        for species, frac in self.basis:
+            x = frac[0] * self.cell[0][0] + frac[1] * self.cell[1][0] + frac[2] * self.cell[2][0]
+            y = frac[0] * self.cell[0][1] + frac[1] * self.cell[1][1] + frac[2] * self.cell[2][1]
+            z = frac[0] * self.cell[0][2] + frac[1] * self.cell[1][2] + frac[2] * self.cell[2][2]
+            lines.append(f'{species} {x} {y} {z}')
+        return '\n'.join(lines) + '\n'
+
+    def write_seed(self) -> Path:
+        path = Path(self.seed_filename)
+        path.write_text(self._seed_text())
+        return path
+
+    def argv(self, *, include_export: bool = True) -> list[str]:
+        args = ['atomsk', str(Path(self.seed_filename))]
+        if self.duplicate is not None:
+            args.append('-duplicate')
+            args.extend(map(str, self.duplicate))
+        return args
+
+    def to_command(self, *, include_export: bool = True) -> str:
+        return shlex.join(self.argv(include_export=include_export))
+
+    def prepare_run(self) -> None:
+        self.write_seed()

pyatomsk-0.3.0/pyatomsk/view.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Union
+
+from voltsdk import PluginArtifact, SpatialAssembler, open_in_volt
+
+Pathish = Union[str, os.PathLike]
+Source = Union[Pathish, PluginArtifact]
+
+_GLB_SUFFIXES = {'.glb', '.gltf'}
+
+
+def _is_glb(path: Path) -> bool:
+    return path.suffix.lower() in _GLB_SUFFIXES or path.name.lower().endswith('.glb.zst')
+
+
+def _as_glb(source: Source, *, output_path: Pathish | None = None, **kwargs: Any) -> Path | str:
+    # voltsdk artifacts already know how to convert themselves to GLB.
+    if isinstance(source, PluginArtifact):
+        return source.glb(output_path=output_path, **kwargs)
+
+    path = Path(os.fspath(source))
+    if _is_glb(path):
+        return path
+
+    target = Path(output_path).expanduser() if output_path else path.with_suffix('.glb')
+    return SpatialAssembler().glb(path, output_path=target, **kwargs)
+
+
+def view(
+    source: Source | Sequence[Source],
+    *,
+    output_path: Pathish | None = None,
+    title: str | None = None,
+    volt_url: str | None = None,
+    open_browser: bool = True,
+    **kwargs: Any,
+) -> str:
+    """Open an analysis artifact, a GLB, or a path (or a list of them) in the VOLT canvas.
+
+    Analysis files (``.json`` / ``.msgpack``) are converted to GLB via voltsdk's
+    ``SpatialAssembler`` (the exporter is auto-detected from the payload); GLBs are
+    passed through untouched. Compute stays local — ``voltsdk.open_in_volt`` serves the
+    asset from a local http server. Returns the viewer URL.
+
+    ``output_path`` only applies to a single source; a list uses each asset's default
+    ``.glb`` path so multiple layers don't collide. Extra keyword arguments (e.g.
+    ``exporter='DislocationExporter'``) are forwarded to the GLB conversion.
+    """
+    if isinstance(source, (str, os.PathLike, PluginArtifact)):
+        glb = _as_glb(source, output_path=output_path, **kwargs)
+        return open_in_volt(glb, title=title, volt_url=volt_url, open_browser=open_browser)
+
+    frames = [_as_glb(item, **kwargs) for item in source]
+    return open_in_volt(frames, title=title, volt_url=volt_url, open_browser=open_browser)

pyatomsk-0.3.0/pyatomsk.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: pyatomsk
+Version: 0.3.0
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: voltsdk>=3.0.0
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python

pyatomsk-0.3.0/pyatomsk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+setup.py
+pyatomsk/__init__.py
+pyatomsk/atomsk.py
+pyatomsk/commands.py
+pyatomsk/dislocations.py
+pyatomsk/structures.py
+pyatomsk/view.py
+pyatomsk.egg-info/PKG-INFO
+pyatomsk.egg-info/SOURCES.txt
+pyatomsk.egg-info/dependency_links.txt
+pyatomsk.egg-info/requires.txt
+pyatomsk.egg-info/top_level.txt

pyatomsk-0.3.0/pyatomsk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyatomsk-0.3.0/pyatomsk.egg-info/requires.txt

@@ -0,0 +1 @@
+voltsdk>=3.0.0

pyatomsk-0.3.0/pyatomsk.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyatomsk

pyatomsk-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyatomsk-0.3.0/setup.py

@@ -0,0 +1,12 @@
+from setuptools import find_packages, setup
+
+
+setup(
+    name="pyatomsk",
+    version="0.3.0",
+    packages=find_packages(),
+    install_requires=[
+        "voltsdk>=3.0.0",
+    ],
+    python_requires=">=3.10",
+)