.. _installation:

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

ToFUL can be used in two ways: through the hosted web application (no
installation required) or by running it locally on your own machine.

.. contents:: On this page
   :local:
   :depth: 2

----

Option 1 — Hosted Web App
--------------------------

The fastest way to use ToFUL is the hosted Streamlit application. No
installation, no dependencies, works on any device with a browser.

`→ Open ToFUL on Streamlit <https://toful1.streamlit.app/>`_

----

Option 2 — Local Installation
------------------------------

Requirements
~~~~~~~~~~~~

* Python 3.9 or later
* pip

Step 1 — Clone the repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   git clone https://github.com/pranava-ba/ToFUL.git
   cd ToFUL

Step 2 — Install dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pip install -r requirements.txt

The ``requirements.txt`` includes:

.. code-block:: text

   streamlit>=1.32.0
   numpy>=1.24.0
   scipy>=1.11.0
   sympy>=1.12
   mpmath>=1.3.0
   plotly>=5.18.0
   pandas>=2.0.0

Step 3 — Run the app
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   streamlit run app.py

The app will open automatically in your browser at ``http://localhost:8501``.

.. note::

   All three files — ``app.py``, ``core.py``, and ``toful_parser.py`` — must
   be in the **same directory** when you run the app.

----

Option 3 — Virtual Environment (Recommended)
---------------------------------------------

Using a virtual environment keeps ToFUL's dependencies isolated from your
system Python.

.. code-block:: bash

   # Create environment
   python -m venv toful-env

   # Activate it
   source toful-env/bin/activate        # macOS / Linux
   toful-env\Scripts\activate           # Windows

   # Install and run
   pip install -r requirements.txt
   streamlit run app.py

----

Verifying the Installation
---------------------------

To confirm everything is working correctly without launching the UI:

.. code-block:: bash

   python -c "
   import core, toful_parser
   import numpy as np

   x, _, _ = core.parse_range_input('0,1,2,3,...')
   vr = core.validate_drv_probabilities(
       '0.3*(0.7**x) if x>=0 else 0', x[:200], True
   )
   print('Valid:', vr.is_valid)
   print('Sum:  ', round(vr.integral_or_sum, 6))
   "

Expected output::

   Valid: True
   Sum:   1.0

----

Optional Dependencies
----------------------

ToFUL automatically uses these packages when available for higher precision
and symbolic computation. They are included in ``requirements.txt`` but
can also be installed separately:

``sympy``
   Enables exact symbolic moment computation for distributions without
   ``if/else`` conditionals (e.g. Normal, Beta). Falls back gracefully to
   numerical integration if not installed.

``mpmath``
   Enables arbitrary-precision integration for display precision above 12
   decimal places. Falls back to SciPy ``quad`` if not installed.

Next Steps
----------

* :doc:`quickstart` — calculate your first moments in under 5 minutes
* :doc:`input-syntax` — learn the expression syntax ToFUL accepts