TopoVec

TopoVec is a Python toolkit for constructing, analyzing, and visualizing 3D vector and director fields, with a focus on topological solitons and liquid-crystal workflows.

Quick Start

Install TopoVec into a fresh project environment:

uv init my_topovec_project
cd my_topovec_project
uv add topovec

For all optional backends:

uv add topovec --all-extras

See docs/guides/installation.md for full installation options.

Highlights

• 3D vector-field and director-field workflows on structured grids.
• Ansatz, coordinate-system, section, and I/O helpers for field construction.
• Multiple rendering backends and notebook-oriented exploration workflows.
• A dockable PySide6 desktop viewer for browsing NPZ/SAD states via topovec view.

Project Layout

• src/topovec contains the main package, including the core abstractions, ansatz helpers, and optional backend integrations.
• notebooks contains demo and workflow notebooks.
• docs contains the Sphinx/MyST documentation sources and API reference.
• tests contains regression and API-level tests.

Getting Started

• Installation: docs/guides/installation.md
• Notebooks and interactive workflows: docs/guides/notebooks.md

Desktop Viewer

topovec view is the native desktop frontend for TopoVec. It opens .npz and .sad state files in a dockable PySide6 window with built-in topovec.mgl scenes, auto-generated property controls, Python reproduction snippets, recent-files history, and high-resolution image and video export.

Install the GUI stack together with the ModernGL backend:

uv tool install 'topovec[view]'

For a one-shot launch without a persistent install, request the same extra explicitly:

uv tool run --from 'topovec[view]' topovec view

Then launch the desktop viewer:

topovec view path/to/state.npz
topovec view path/to/trajectory.sad path/to/other_state.npz

On Linux, topovec view may show OpenGL compositing artifacts under Qt Wayland on some systems. If you see overbright or unstable rendering, prefer the X11 Qt backend:

QT_QPA_PLATFORM=xcb topovec view path/to/state.npz

Current topovec view scope:

• One active central viewport with dockable source, property, and snippet panels.
• Read-only browsing of NPZ and SAD states.
• Built-in topovec.mgl scenes with auto-generated property controls.
• High-resolution image export from the current render state.
• Video export from trajectories using the live render session.

Documentation

The documentation sources live in docs/ and the canonical hosted target is Read the Docs.

The English Mathematical Reference and Visual Atlas defines the quantities, numerical approximations, and display parameters of the built-in scenes. Its LaTeX sources and reproducible illustrations live in tex/visualization/, with tex/visualization_reference.tex as the entry point.

To build the documentation locally:

uv run --extra docs --extra mgl --extra marimo --extra matplotlib --extra ti --extra sad sphinx-build -b html docs docs/_build/html

Development

Developer-oriented repository notes and common operations are documented in DEVELOPMENT.md.