License
========

prophys is proprietary software by RhineQC GmbH. This page explains what
that means in practice: what runs without a license, what needs one, and
how the two are enforced.

Free tier vs. licensed use
------------------------------

prophys is one installable package with two parts inside it. The Python
frontend is the DSL you write models in, fully open to read, documented,
and unrestricted. The compiled native core, ``prophys._core``, performs
the actual numerics and enforces a **free-tier object limit**:

.. list-table::
   :header-rows: 1

   * - Tier
     - Limit
     - What counts
   * - Free
     - Up to 250 objects per structural kernel call
     - Points in a ``PointList``, vertices in a ``Polygon``, segments in a
       ``LineList``, halfspaces in a ``Polyhedron``, cells in a raster
       ``Field``, ...
   * - Licensed
     - No limit
     - Same, unbounded

A model that stays within the free tier, the kind of model this
documentation's examples and gallery use, runs with **no license file at
all**. This is deliberate: evaluation, teaching, prototyping, and small
studies should never require going through a licensing step.

What does *not* count towards the limit
-------------------------------------------

The 250-object limit applies specifically to **structural model size**,
the geometry and data structures you declare. It does **not** apply to:

- Monte-Carlo marginalization sample counts (``n_samples`` in
  :meth:`ProbabilityModel.compile <prophys.domain.ProbabilityModel.compile>`)
- The number of observations passed to :func:`~prophys.engine.calibrate` /
  :func:`~prophys.engine.finetune`
- Dense evaluation grids used for plotting (e.g. a risk-map
  :class:`~prophys.structures.Grid`)
- Training iterations, gradient steps, or optimizer calls

In other words, **you can calibrate a small model against as much data, at
as high a Monte-Carlo precision, as you like, entirely for free.** The
license question is only ever "how big is the *model itself*, how many
points, vertices, segments, or raster cells does it declare", matching
the intuitive reading of "250 objects, e.g. points or contents in a
``PointList``."

.. code-block:: python

   import prophys as prp

   # Free tier: 200 points in a PointList, 4 polygon vertices, well under 250.
   houses = prp.PointList(house_coords_200x2, site)
   zone = prp.Polygon(four_vertices, site)

   # Also free: marginalizing over 10,000 Monte-Carlo samples of a tiny model.
   compiled = model.compile(n_samples=10_000)

   # Requires a license: 5,000 points in a PointList.
   many_points = prp.PointList(coords_5000x2, site)

Configuring a license
--------------------------

.. code-block:: bash

   export PROPHYS_LICENSE=/path/to/license.key

``PROPHYS_LICENSE`` may point to a license file or contain the license text
directly. A license is an Ed25519-signed document (licensee, issued,
expiry). The verification key is compiled into ``prophys._core``, so
a license cannot be forged or the check bypassed from Python.

.. code-block:: python

   from prophys import _core as prophys_core

   valid, licensee, detail = prophys_core.license_status()
   print(valid, licensee, detail)

   print(prophys_core.free_tier_limit())  # 250

Exceeding the free tier without a license raises a clear error naming the
kernel and the object count involved. Nothing is silently truncated,
degraded, or approximated:

.. code-block:: text

   INVALID_ARGUMENT: prophys_points_closest_hard_fwd: model size (300 objects)
   exceeds the prophys free tier (250 objects). Set PROPHYS_LICENSE to a
   valid license to run models of this size.