Notebooks and remote systems

v_ase can display a lightweight interactive model inside Jupyter, open the full workspace in an external browser, or keep file I/O and analysis beside data on an SSH host.

Jupyter auto-detection 

Inside an active Jupyter kernel, the default view(atoms) result is a view-only iframe below the cell:

from ase.build import molecule
from v_ase import view

view(molecule("H2O"))

The inline view supports orbit, pan, zoom, and trajectory playback. It omits the full editing workspace. Outside Jupyter, the same default opens the normal browser application.

`%v_ase` display preference 

Importing v_ase in an active IPython shell registers a line magic:

%v_ase inline
view(atoms)

%v_ase browser
editor = view(atoms, block=False)

%v_ase auto

inline makes subsequent default calls return an iframe-capable handle.
browser opens the full external interface.
auto restores kernel detection.
%v_ase or %v_ase status prints the current mode.

Register explicitly when necessary:

%load_ext v_ase.notebook

Per-call notebook override 

The notebook argument takes priority for one call:

view(atoms, notebook="inline")   # or True
view(atoms, notebook="browser")  # or False

If assigning an inline handle instead of leaving it as the cell’s last value, display it explicitly:

from IPython.display import display

editor = view(atoms, notebook="inline")
display(editor)

The inline handle exposes notebook_url; a non-inline workspace handle exposes the complete url. Close long-lived non-blocking handles explicitly.

Return edited structures from notebooks 

The complete external editor can block a cell until the browser document is finalized:

edited = view(atoms, notebook="browser", viz_only=False, block=True)

Or continue notebook execution and poll/close a handle:

editor = view(atoms, notebook="browser", viz_only=False, block=False)
current = editor.get_atoms()
editor.close()

One-command remote files 

Install the same v_ase release locally and on the SSH host, then launch from the local terminal:

v_ase gui USER@SERVER:/absolute/path/to/STRUCTURE

An SSH config alias works:

v_ase gui physics:/data/run-42/trajectory.extxyz

v_ase selects private loopback endpoints, starts the remote backend, and carries the backend plus forwarding listener over one SSH connection. The browser opens locally. Keeping startup and forwarding on one connection matters when a cluster alias load-balances logins across multiple nodes.

Where work happens 

Remote host	Local computer
Source-file I/O and ASE parsing	Browser UI
Indexed/lazy trajectory access	WebGL rendering
Volumetric sampling and isosurfaces	Camera and pointer interaction
RDF, registry, relaxation, and other backend calculations	Final browser canvas capture before encoded output

The source file is not downloaded as a normal local file. Remote sessions stream the requested frame or derived payload through the encrypted tunnel. Exports generated by the remote backend can still be saved through the local browser/command workflow as supported by the selected output.

Select the remote Python 

Non-interactive SSH sessions may not source .bashrc or activate a Conda environment. Specify the exact Python executable for one launch:

v_ase gui physics:/data/POSCAR \
  --remote-python /home/user/miniconda3/envs/vase/bin/python

Persist it for that exact host string:

v_ase remote configure physics \
  --python /home/user/miniconda3/envs/vase/bin/python

v_ase remote show physics
v_ase gui physics:/data/POSCAR

The executable must be absolute and contain a compatible v_ase installation. Upgrade both endpoints before using a newly added backend or browser schema.

Jump hosts and SSH configuration 

Put normal transport policy in ~/.ssh/config, including keys, aliases, ProxyJump, and host verification. v_ase invokes SSH using the same host text to the left of :. It does not store passwords or private keys.

Example:

Host compute
    HostName compute.internal.example
    User researcher
    ProxyJump login.example

v_ase gui compute:/scratch/run/POSCAR

Manual headless workflow 

For a local headless session or a transport you manage yourself:

v_ase gui /absolute/path/to/FILE --no-browser

The printed URL is loopback-only. Do not bind or publish it to an untrusted network. Forward the chosen port through an authenticated SSH connection when manual tunneling is necessary.

Large trajectory behavior 

Remote sessions force frame streaming for every trajectory size. Indexed XDATCAR and native ASE .traj readers request frames on demand in View; compatible numeric LAMMPS dumps use a byte-offset index. Entering Edit may materialize all frames because topology and physical trajectory operations need editable objects.

Use View for inspection and analysis of very large remote trajectories, and open only the target frame in a separate Edit document before a topology change.

Failure and cleanup 

If automatic browser launch fails, the usable local URL remains printed. The SSH connection and remote process are cleaned up when the last connected workspace closes normally. Ctrl+C interrupts a non-blocking/headless session.

Common failures—remote executable not found, version mismatch, unavailable forwarded port, host key problems, or load-balanced tunnel drift—are covered in Troubleshooting.