lcsim 0.1.4

LCSim - liquid crystal simulator.

LCSim

Liquid crystal simulation tools and command-line utilities.

Installation

LCSim is published on PyPI. For regular use, install it as a uv tool. Detailed OS-specific instructions:

• Windows: WINDOWS-INSTALL.md
• Ubuntu: UBUNTU-INSTALL.md

The default dependency set is intentionally light: it is enough for the lcsim dispatcher and shared Python code, but not for running simulations, opening the GUI, viewing files, or rendering videos. Install one profile for the workflow you actually use. Do not install every extra at once: CUDA profiles conflict by design. For every runtime mode in one environment, use all-cu (all-cu13) or all-cu12. For one mode, use a convenience profile such as run-cu13 or gui-cu13. For a mixed environment, choose one low-level GPU extra such as gpu-cu13 and add non-conflicting feature extras (sad, gui, view, render, run-notify) around it.

Recommended PyPI tool installs:

# All runtime modes, recommended CUDA 13 profile.
uv tool install 'lcsim[all-cu]'

# Batch simulation, recommended CUDA 13 profile.
uv tool install 'lcsim[run-cu13]'

# Interactive GUI, recommended CUDA 13 profile.
uv tool install 'lcsim[gui-cu13]'

# New TopoVec-based renderer for SAD/TopoVec state files.
uv tool install 'lcsim[render]'

# Saved-file viewer with LCSIM scenes and TopoVec scenes.
uv tool install 'lcsim[view]'

# Optional Telegram notifications for `lcsim run`.
uv tool install 'lcsim[run-cu13,run-notify]'

# Combined run + GUI environment with one shared GPU profile.
uv tool install 'lcsim[gpu-cu13,sad,gui]'

all-cu and all-cu13 install the CUDA 13 runtime, TopoVec CUDA backend, lcsim run, lcsim gui, lcsim view, lcsim render, run notifications, optics, and legacy renderer Python dependencies. all-cu12 keeps the lcsim runtime on the CUDA 12 family and omits TopoVec's CUDA 13-only CUDA backend. Legacy lcsrender still needs a system ffmpeg executable on PATH.

For one-off execution without installing persistent commands:

uvx --from 'lcsim[run-cu13]' lcsim run --help
uvx --from 'lcsim[gui-cu13]' lcsim gui --help

From a repository checkout, use the same extras with uv sync --extra ... and run commands with uv run ....

Command-line tools

The primary public entry point is now lcsim:

lcsim --help
lcsim run --help
lcsim gui --help
lcsim view --help
lcsim render --help

Typical usage:

# Run an off-screen simulation.
lcsim run --preset consym --history HISTORY.json --period 10 --output --sad

# Open the interactive viewer.
lcsim gui

# View a saved simulation state without starting CUDA runtime.
lcsim view run.sad

# Render a SAD file with simulation-time video sampling.
lcsim render run.sad --scene "Jones RGB" --output run.mp4 --fps 25

Legacy commands remain available as compatibility wrappers, but they print a deprecation notice:

• lcsrun: use lcsim run ... for new workflows.
• lcsgui: use lcsim gui ... for new workflows.
• lcsrender: legacy renderer; use lcsim render ... for the new renderer.
• lcsoptics: optional optics utility. Install the optics extra if you want to use it.

Legacy lcsrender requires a system ffmpeg executable on PATH; the new lcsim run path writes SAD and leaves video generation to lcsim render.