.. _python_API:

.. currentmodule:: flow360

*************
Python API 🐍
*************

The Flow360 Python API provides a powerful, user-friendly interface to configure, run, and analyze Computational Fluid Dynamics (CFD) simulations. Built with modern Python practices, the API leverages Pydantic models for robust configuration and validation, making it both flexible and reliable.

.. grid:: 2

    .. grid-item-card:: 📚 First Steps
        :link: getting_started/index
        :link-type: doc
        
        New to Flow360? Start here to learn the basics and set up your environment.

    .. grid-item-card:: 🔬 Basic Simulations
        :link: basic_simulations/index
        :link-type: doc
        
        Run your first CFD simulations with step-by-step guides.

    .. grid-item-card:: 🧪 Advanced Use Cases
        :link: advanced_simulations/index
        :link-type: doc
        
        Explore complex setups, multiphysics coupling, and optimization workflows.

    .. grid-item-card:: 📊 Post-Processing
        :link: post_processing/index
        :link-type: doc
        
        Extract insights from your simulation results with powerful analysis tools.

    .. grid-item-card:: 🔄 Workflow Management
        :link: workflow_management/index
        :link-type: doc
        
        Efficiently organize and manage multiple simulation campaigns.

    .. grid-item-card:: 📖 API Reference
        :link: api/index
        :link-type: doc
        
        Comprehensive documentation of classes, methods, and parameters.

Installation and Setup
======================

Getting Started
---------------

Before using Flow360, you need to:

1. Sign up for a user account at `flow360.simulation.cloud <https://flow360.simulation.cloud>`_
2. Obtain your API key from your account profile
3. Install the Python package and configure your API key

Package Installation
~~~~~~~~~~~~~~~~~~~~

Install the latest stable version:

.. code-block:: bash

    pip install -U flow360

To install a specific version of Python API, for example 24.11:

.. code-block:: bash

   pip install "flow360==24.11.*"

For pre-release versions:

.. code-block:: bash

    pip install -U flow360 --pre

To install a specific Github branch of Python API, for example `develop` branch:

.. code-block:: bash

   pip install git+https://github.com/flexcompute/Flow360.git@develop

API Key Configuration
~~~~~~~~~~~~~~~~~~~~~

Most of the functionalities (like uploading mesh and submitting case) of Flow360 Python API requires setting up proper API key for authentication.
The API key can be obtained from the Flow360 WebUI by clicking on your avatar on the top right of your workspace then clicking on your **Account** then **Python Authentication**. Please contact customer support for more information.

.. figure:: Figures/api_key_getting.png
   :width: 95%
   :align: center

   *Accessing your API key.*

To setup the API key authentication, you can use one of the following methods:
**Method 1: Global Configuration (Recommended)**

.. tabs::

   .. group-tab:: On Linux |:penguin:| & MacOS |:apple:|
      
      In the command line. Run the following command.

      .. code-block:: bash

         flow360 configure --apikey XXX


   .. group-tab:: On Windows |:window:|

      If you want to configure the API key on Windows, you can run the following command in the command prompt.

      .. code-block:: bash

         flow360 configure --apikey XXX


      

This will prompt you to enter your API key and store it in ``~/.flow360``


**Method 2: Configure in Python**


      .. code-block:: python

         import flow360 as fl
         fl.configure(apikey='XXX')


**Method 3: Environment Variable in Shell**


.. tabs::

   .. group-tab:: On Linux |:penguin:| & MacOS |:apple:|
      
      In the command line. Run the following command.

      .. code-block:: bash

         export FLOW360_APIKEY="XXX"



   .. group-tab:: On Windows |:window:|

      In the PowerShell. Run the following command.

      .. code-block:: powershell

         $Env:FLOW360_APIKEY="XXX"



**Method 4: Environment Variable in Python**

.. code-block:: python

    import os
    os.environ["FLOW360_APIKEY"] = "XXX"
    import flow360

.. note::
   The ``FLOW360_APIKEY`` environment variable takes precedence over the configuration file.


Testing Your Installation
~~~~~~~~~~~~~~~~~~~~~~~~~

To verify your installation is working correctly:

.. code-block:: python

    import flow360
    print(flow360.__version__)  # Check installed version

.. toctree::
   :hidden:

   getting_started/index
   basic_simulations/index
   advanced_simulations/index
   post_processing/index
   workflow_management/index
   tutorials/index
   migration_guide/index
   api/index