Metadata-Version: 2.4
Name: topovec
Version: 0.1.9
Summary: Visualizer of 3d vector field with accent of topological solitons.
Project-URL: Repository, https://gitlab.com/alepoydes/topovec
Project-URL: Issues, https://gitlab.com/alepoydes/topovec/-/issues
Author-email: Igor Lobanov <lobanov.igor@gmail.com>
License-Expression: MIT
License-File: LICENSE.matplotlib
License-File: LICENSE.md
Keywords: liquid crystal,magnetization,physics,soliton,topology,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: <3.14,>=3.10
Requires-Dist: numpy>=2.1
Requires-Dist: pillow>=11.1.0
Requires-Dist: rich>=13.9.4
Provides-Extra: cuda
Requires-Dist: cuda-toolkit[cudart,cufft,nvrtc]==13.*; extra == 'cuda'
Requires-Dist: cupy-cuda13x>=14.0.1; extra == 'cuda'
Provides-Extra: docs
Requires-Dist: myst-parser>=4.0.0; extra == 'docs'
Requires-Dist: numpydoc>=1.7.0; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.15.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=2.0.0; extra == 'docs'
Requires-Dist: sphinx>=7.0.0; extra == 'docs'
Provides-Extra: gui
Requires-Dist: moderngl>=5.12.0; extra == 'gui'
Requires-Dist: pyside6>=6.8; extra == 'gui'
Provides-Extra: marimo
Requires-Dist: anywidget>=0.9; extra == 'marimo'
Requires-Dist: marimo; extra == 'marimo'
Provides-Extra: matplotlib
Requires-Dist: matplotlib>=3.10.1; extra == 'matplotlib'
Provides-Extra: mgl
Requires-Dist: moderngl>=5.12.0; extra == 'mgl'
Provides-Extra: render
Requires-Dist: imageio[ffmpeg]; extra == 'render'
Requires-Dist: moderngl>=5.12.0; extra == 'render'
Provides-Extra: sad
Requires-Dist: sadcompressor>=0.0.2; extra == 'sad'
Provides-Extra: ti
Requires-Dist: taichi>=1.7.3; extra == 'ti'
Provides-Extra: video
Requires-Dist: imageio[ffmpeg]; extra == 'video'
Provides-Extra: view
Requires-Dist: imageio[ffmpeg]; extra == 'view'
Requires-Dist: moderngl>=5.12.0; extra == 'view'
Requires-Dist: pyside6>=6.8; extra == 'view'
Requires-Dist: sadcompressor>=0.0.2; extra == 'view'
Requires-Dist: taichi>=1.7.3; extra == 'view'
Description-Content-Type: text/markdown

# 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:

```sh
uv init my_topovec_project
cd my_topovec_project
uv add topovec
```

For all optional backends:

```sh
uv add topovec --all-extras
```

See [docs/guides/installation.md](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](docs/guides/installation.md)
- Notebooks and interactive workflows: [docs/guides/notebooks.md](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:

```sh
uv tool install 'topovec[view]'
```

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

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

Then launch the desktop viewer:

```sh
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:

```sh
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.

To build the documentation locally:

```sh
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](DEVELOPMENT.md).
