Installation
=============

.. code-block:: bash

   pip install prophys

That's it. ``prophys`` ships as prebuilt binary wheels (including the
compiled native core, ``prophys._core``) for common platforms
(Linux/macOS/Windows, x86_64 and arm64). There is no source compilation
step and no Rust toolchain required.

With optional extras:

.. code-block:: bash

   pip install "prophys[viz]"          # matplotlib plotting helpers (prophys.plot)
   pip install "prophys[geo]"          # shapely/pyproj GeoJSON import
   pip install "prophys[inference]"    # NumPyro bridge for NUTS/SVI

Requirements: Python >= 3.10. JAX and Optax are installed automatically as
dependencies.

Licensing and the free tier
-----------------------------

Small models run immediately, with no license file. Every native kernel
call touching at most 250 structural objects (points, polygon vertices,
segments, raster cells, ...) computes freely, which covers the
documentation's own examples and gallery, teaching use, and prototyping.
Larger models require a license:

.. code-block:: bash

   export PROPHYS_LICENSE=/path/to/license.key

See :doc:`license` for exactly what counts towards the 250-object limit
(structural model size) and what does not (Monte-Carlo sample counts,
observation counts, training iterations).

Verifying the installation
----------------------------

.. code-block:: python

   import prophys as prp
   import jax.numpy as jnp

   site = prp.Frame("site")
   a = prp.PointList(jnp.array([[0.0, 0.0]]), site)
   b = prp.PointList(jnp.array([[3.0, 4.0]]), site)
   print(a.closest_distance(b).evaluate())  # -> [5.]  (via the native core)

GPU note
----------

The native kernels are CPU targets. Models evaluated on GPU-resident arrays
will fail with a platform error rather than silently falling back. Move
arrays to host memory for now. CUDA kernels are a planned future addition.