LCSim

Liquid crystal simulation tools and command-line utilities.

The documentation index covers physical models and supported workflows. Implementation references are in doc/developer.

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 the profile for the workflow you actually use.

Use Python 3.13 for tool installs. The current Taichi-based viewer/render stack does not support Python 3.14, and older LCSim releases had incomplete Python compatibility metadata. Keep the >=0.1.10 lower bound unless you intentionally install an older release.

Recommended PyPI tool installs:

# All runtime modes, recommended CUDA 13 profile.
uv tool install --python 3.13 'lcsim[all-cu13]>=0.1.10'

# Batch simulation, recommended CUDA 13 profile.
uv tool install --python 3.13 'lcsim[run-cu13]>=0.1.10'

# Live simulation GUI, recommended CUDA 13 profile.
uv tool install --python 3.13 'lcsim[gui-cu13]>=0.1.10'

# Saved-file viewer with LCSIM scenes and TopoVec scenes, no simulation runtime.
uv tool install --python 3.13 'lcsim[view]>=0.1.10'

# TopoVec-based renderer for SAD/TopoVec state files, no simulation runtime.
uv tool install --python 3.13 'lcsim[render]>=0.1.10'

Use view-lite or render-lite when you want saved-file tools without TopoVec CUDA render scenes. Use all-cu12, run-cu12, or gui-cu12 only when the calculation runtime must stay on the CUDA 12 package family. Legacy lcsrender still needs a system ffmpeg executable on PATH.

For one-off execution without installing persistent commands:

uvx --python 3.13 --from 'lcsim[run-cu13]>=0.1.10' lcsim run --help
uvx --python 3.13 --from 'lcsim[gui-cu13]>=0.1.10' lcsim gui --help

From a repository checkout, use the same extras with uv sync --python 3.13 --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 extract --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; read-only Settings appear beside Data Sources.
lcsim view run.sad

# Extract selected SAD frames to NPZ snapshots.
lcsim extract run.sad --time 1.0 --output-dir frames

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

Inside lcsim view, use File -> Save Current State NPZ... to save the selected LCSIM SAD frame or NPZ entry as a full snapshot NPZ file.

Mode documentation:

• lcsrun: use lcsim run ... for new workflows.
• lcsgui: use lcsim gui ... for new workflows.
• lcsim extract: extract selected SAD frames to NPZ snapshots.
• 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 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.
• lcsextract: use lcsim extract ... for new workflows.
• lcsrender: use lcsim render ... for the new renderer.

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