Getting Started
===============

This page will help you get up and running with the Python Client.

Run a Simulation
----------------

In order to use the Client, you must have a Tyba PAT (Personal Access Token). The `Authentication`_ section below
explains how to store your PAT in your local environment. With the PAT stored, we can run our first simulation and
view the results:

#. Make the necessary imports:

    .. code-block:: python

        import os
        from generation_models import PVGenerationModel, SingleAxisTracking
        from tyba_client.client import Client

#. Define a simple model:

    .. code-block:: python

        model = PVGenerationModel(
           solar_resource=(40.6685396, -73.9345585),
           inverter="Delta Electronics: M80U_XXX [480V]",
           pv_module="Boviet Solar Technology Co._ Ltd. BVM6612M-315",
           system_design=SystemDesign(
               dc_capacity=2000.0,
               ac_capacity=1500.0,
               poi_limit=15000.0,
               gcr=0.38,
               tracking=SingleAxisTracking(
                   rotation_limit=45.0,
                   backtrack=True
               )
           ),
          project_term=1
        )

#. Read the PAT from the environment and instantiate a client

    .. code-block:: python

        PAT = os.environ["TYBA_PAT"]
        client = Client(PAT)

#. Schedule the model run:

    .. code-block:: python

       res = client.schedule(model)
       id_ = res.json()["id"]
       print(res.text)

    You will see an id print, confirming that the run has been scheduled.

#. Wait to receive the results:

    .. code-block:: python

        results = client.wait_on_result(id_)

    For more details on the schedule & receive process, see :ref:`scheduling_receiving`.

#. View results

    .. code-block:: python

       # Results is a dictionary. To review keys:
       print(results.keys())

       # Review System Power 8760
       results['system_power']

Next
----

* The :doc:`usage` page digs a bit deeper into the mechanics of the Client and its models
* More complex examples can be found on the :doc:`examples` page
* For info on specific model objects/parameters, check out the
  :doc:`generation_models documentation <generation_models:index>`
* For info on options within the Client, check out the :doc:`api` page

Authentication
--------------

As mentioned above, you must have a Tyba PAT to use the Client. If you do not have or know your
PAT, please contact us.

Mac or Linux instructions
^^^^^^^^^^^^^^^^^^^^^^^^^

Shell Environment (preferred)
"""""""""""""""""""""""""""""
Save your Tyba PAT in the shell's environment:

#. Add ``TYBA_PAT="your-pat-in-quotes"`` to a new line in ~/.bashrc
#. To check, open a **new** shell/terminal and run ``env`` and confirm ``TYBA_PAT`` is present and properly set

This approach is preferred even if you are running a Jupyter notebook because it keeps the PAT from being exposed if
the notebook/script is shared

Jupyter Notebook
"""""""""""""""""
Save your Tyba PAT in the notebook's environment:

#. In a notebook cell, enter the following:
    .. code-block:: python

        %env TYBA_PAT=your_pat_without_quotes
#. The cell will return your key with "env: TYBA_PAT = your_pat_without_quotes"
#. To keep the PAT secure, delete the previous cell. You will need to repeat this process each time you open the notebook

Windows Instructions
^^^^^^^^^^^^^^^^^^^^

Shell Environment
"""""""""""""""""
On a Windows machine, the simplest (but less secure) approach is to hardcode the PAT directly into your script, i.e.
replace ``PAT = os.environ["TYBA_PAT"]`` with ``PAT="your-pat-in-quotes"``

Jupyter Notebook (preferred)
""""""""""""""""""""""""""""
See the `Jupyter notebook`_ section above.