#+TITLE: Wire Cell Toolkit Python

* What's here.

This package provides Python modules in the ~wirecell~ namespace as well as
various ~wirecell-*~ command line programs.  These support the Wire Cell Toolkit
but do not depend on it.  If this package is available during the WCT build
process then some additonal unit tests can run using ~wirecell-*~ programs.

Some of the functionality provided includes converters and generators of major
WCT input data files including:

- field response functions
- wire geometry
- diagnostic plots

* Installation

It is recommended to use [[https://github.com/astral-sh/uv][uv]] for user and developer tasks.

** User

You can use "uv run" to run the command line programs "live":

#+begin_example
uv run --with git+https://github.com/wirecell/wire-cell-python wirecell-util --help
#+end_example

Or to install as a "uv tool"

#+begin_example
uv tool install git+https://github.com/wirecell/wire-cell-python
wcpy util  --help
#+end_example

To later upgrade

#+begin_example
uv tool upgrade wirecell
#+end_example

Or to later uninstall

#+begin_example
uv tool uninstall wirecell
#+end_example

** Developer

#+begin_example
git clone git@github.com:WireCell/wire-cell-python.git
cd wire-cell-python
uv sync
uv run wcpy util --help
#+end_example

This will use a local virtualenv which does not require explicit activation when
using ~uv run~.  Or, you may do the usual

#+begin_example
source .venv/bin/activate
wcpy util --help
#+end_example

** Packager

To build a Python wheel package:

#+begin_example
uv build
#+end_example

Exercise it in place

#+begin_example
uvx dist/wirecell-0.1.1-py3-none-any.whl
#+end_example

** Optional dependencies

Some dependencies are optional and not installed by default.  In particular,
PyTorch is a very large package and not generally required and so is kept
optional.  In order to use optional functionality must add ~torch~ to the
commands above:

For "live" running:

#+begin_example
uv run --with torch --with git+https://github.com/wirecell/wire-cell-python wcpy util --help
#+end_example

For "tool" based installation:

#+begin_example
uv tool install --with torch git+https://github.com/wirecell/wire-cell-python
#+end_example

For developers, the "sync" command needs additional info:

#+begin_example
uv sync --all-extras
#+end_example


* Documentation

In addition to the online ~-h/--help~ for main and sub commands, some
notes on specific aspects are in [[file:docs/]].  Some in particular

- [[file:docs/developer.org][Developer guidance]]