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

Install an officiel release
------------------------------

GEOP4TH is available as a Python package for Linux, Windows and macOS on `PyPI <https://pypi.org/project/geop4th>`_.

.. tab-set::
   :sync-group: package_manager

   .. tab-item:: with pip
      :sync: 3

      **Pip** is a Python package manager. Please note that before installing GEOP4TH in a virtual environment with pip, you need to 
      have installed python==3.11 beforehand.
      
      In your 📟 **Command Prompt**, after activating the virtual environment in which you want to install GEOP4TH,
      you can proceed using the *pip* command::
	  
         pip install geop4th

   .. tab-item:: with conda 
      :sync: 1

      **Conda** is a package and virutal environment manager. To use it, you first need to install a conda distribution such as `Anaconda <https://www.anaconda.com/docs/main>`_ 
      or `Miniconda <https://www.anaconda.com/docs/getting-started/miniconda/main>`_.

      In your 📟 **Anaconda Prompt**, after activating the virtual environment in which you want to install GEOP4TH,
      you can proceed using either *conda* or *pip*:
	  
      .. tab-set::
          :sync-group: install

          .. tab-item:: conda 
             :sync: 1
          
             .. admonition:: not implemented yet
                :class: attention
		  
                GEOP4TH is not yet available through conda, but it is intended to be available soon via the *conda-forge community channel*!
			 
          .. tab-item:: pip
             :sync: 2
		  
             ::

               pip install geop4th

   .. tab-item:: with mamba
      :sync: 2
      
      **Mamba** is a fast package manager, containing especially ``libmamba`` and ``mamba`` (which allows to run *conda* commands by replacing ``conda`` with ``mamba``).
      To use it, you first need to install a mamba distribution such as `Miniforge <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_ (fresh install).

      In your 📟 **Miniforge Prompt**, after activating the virtual environment in which you want to install GEOP4TH,
      you can proceed using either *conda* or *pip*:
	  
      .. tab-set::
          :sync-group: install

          .. tab-item:: conda 
             :sync: 1  
          
             .. admonition:: not implemented yet
                :class: attention
		  
                GEOP4TH is not yet available through conda, but it is intended to be available soon via the *conda-forge community channel*!
			 
          .. tab-item:: pip
             :sync: 2
		  
             ::

               pip install geop4th

If you are not familiar with virtual environments, please visit `pip <https://pypi.org/project/pip>`_, 
`conda <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`_ or `mamba <https://mamba.readthedocs.io/en/latest>`_ 
websites, or have a look at the :ref:`installation procedure for contributors <install-venv>`.

Install an |IDE|
------------------------------------------------

In order to run *GEOP4TH* functions and use them in your scripts, you will need an |IDE| 
(*Spyder*, *Jupyter Notebook*, *PyDev*, *PyCharm*, *IDLE*, *VS Code*... ) if you do not already have one.
You can manually install one of your choice *(for example Spyder)*:

.. tab-set::
   :sync-group: package_manager

   .. tab-item:: with pip
      :sync: 3
   
      ::
	  
         pip install spyder
		 
         spyder

   .. tab-item:: with conda
      :sync: 1

      ::

         conda install -c conda-forge spyder
    
         spyder
		 
   .. tab-item:: with mamba
      :sync: 2

      ::
	  
         mamba install spyder
		 
         spyder
		 

.. dropdown:: Troubleshooting of Spyder
   :color: warning
   :icon: bug

   If you use Spyder, you might encounter some **kernel issue** when launching it, making you unable to use the IPython Console in Spyder.
   Here are some frequent causes:
   
   - it can be due to the presence of another Spyder installed on your computer. To solve it, go to **Tools** > **Preferences** > **Python Interpreter** 
     and check the checkbox **Internal**. This option enables Spyder to automatically select the kernel corresponding
     to the Python virtual environment from which it has been launched.
	 
   - if you are using *mamba*, it may be an issue between mamba and Spyder. Instead of launching ``mamba activate geoenv``, try to use
     ``conda activate geoenv`` instead, before entering ``spyder`` to run Spyder (the ``(geoenv)`` prefix may not be shown when activating
     your virutal environment with ``conda``, but you can check that your geoenv environment has well been activated with the command ``conda info``)

   - if the previous workarounds do not work, you can also try to uninstall and reinstall *spyder-kernels* and *spyder* in your
     environment
	 
   - if it still does not work, you can try to gain more insight about the bug by lauching the IPython Console in different environments (in Spyder,
     you can do a righ click on *Console 1/A* and open *New console in environment*
	 
   You might also encounter issues with **Qt** (used for the graphical user interface):
   
   - if you encounter an error with loading Qt platform plugin, you can enter the command::

      QT_QPA_PLATFORM=wayland   
	
   If you have troubles for installing Spyder, you may want to try another GEOP4TH installation procedure (with ``pip`` or ``mamba`` instead of ``conda``, see above)
   
   Additionaly, you may want to check that the python version you use is well supported by Spyder.

Import modules
----------------

Finally, you can import the main modules in your |IDE| as follow:

.. code-block:: python3

    from geop4th import (
        geobricks as geo,
        download_fr as dlfr,
        download_wl as dlwl,
        trajplot as tjp,
    )

And workflows can be imported similarly:

.. code-block:: python3

    from geop4th import (
        standardize_fr as stzfr,
        standardize_wl as stzwl,
        cwatm,
    )


.. dropdown:: Module not found
   :color: warning
   :icon: bug

   ::
   
      No module named 'geop4th'

   This error should not happen. However, if it does, you may try to amend the ``PYTHONPATH``.

   You can amend the ``PYTHONPATH`` in your |IDE|, by adding your local 📁 **geop4th** folder.

   .. note::

      We mean your root 📁 **geop4th** folder, not the 📁 **geop4th/geop4th** folder inside.

   Alternatively you can also add your 📁 **geop4th** folder to ``sys.path`` by entering in your |IDE|::

      import sys
      sys.path.append(r"your/path/to/geop4th")



.. |IDE| raw:: html

  <abbr title="Integrated development environment (Spyder, PyCharm, Visual Studio Code...)">IDE</abbr>

.. # define a hard line break for HTML
.. |br| raw:: html

   <br>
   

.. |nbsp| unicode:: 0xA0 
   :trim: