Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update MHKiT-Python installation instructions #75

Open
wants to merge 9 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
169 changes: 139 additions & 30 deletions docs/source/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
MHKiT-Python Installation
=========================

The following sections includes installation instructions for `MHKiT-Python <https://github.com/MHKiT-Software/MHKiT-Python>`_.
The following sections include installation instructions for `MHKiT-Python <https://github.com/MHKiT-Software/MHKiT-Python>`_.

`MHKiT-Python <https://github.com/MHKiT-Software/MHKiT-Python>`_ requires `Python (3.8-3.11) <https://www.python.org/>`_ and has several Python package dependencies.
It is recommended to use the `Anaconda Python Distribution <https://www.anaconda.com/distribution/>`_ to install Python since it includes most of MHKiT-Python's package dependencies.
It is recommended to use `Conda <https://docs.conda.io/projects/conda/en/stable/index.html>`_ to install Python and MHKiT-Python since it includes most of MHKiT-Python's package dependencies.


Requirements
^^^^^^^^^^^^^^^
`MHKiT-Python <https://github.com/MHKiT-Software/MHKiT-Python>`_ requires `Python (3.8-3.11) <https://www.python.org/>`_ and has the following Python packages dependencies:
`MHKiT-Python <https://github.com/MHKiT-Software/MHKiT-Python>`_ requires `Python (3.8-3.11) <https://www.python.org/>`_ and has the following Python package dependencies:

* `Xarray <https://docs.xarray.dev/en/stable/>`_: used for data storage and analysis
* `Pandas <http://pandas.pydata.org>`_: used for data storage and analysis
Expand All @@ -21,49 +21,159 @@ Requirements
* `Requests <https://requests.readthedocs.io/>`_: used to get data from websites
* `Pecos v0.1.9 <https://pecos.readthedocs.io/>`_: used for quality control analysis


Install MHKiT-Python
^^^^^^^^^^^^^^^^^^^^^

Option 1: PIP Install from Python
""""""""""""""""""""""""""""""""""""
Option 1: Using Conda
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer using conda and agree with that as option 1. I think we should further update these steps and discuss git first. This was an issue we ran into at the last training course. When new users come to MHKiT, they very likely want/need the example notebooks. To get those, one needs to use git. An adjustment to these steps could proceed like this:

  • Decide whether to use git.
    • Pros: examples will be installed, enables the developer workflow, users are later one step closer to opening issues and PRs
    • Cons: requires installing / using another software that is not required to run MHKiT
  • If yes git:
    • install git for windows
    • clone repo using the single command line
    • use environment.yml file included in the repo (user workflow) OR pip install the local clone (developer workflow)
  • If no git
    • curl to get environment.yml file and conda install OR pip install

"""""""""""""""""""""

This option is recommended for MHKiT-Python users.
To install MHKiT-Python using `pip <https://pip.pypa.io/en/stable/>`_::
For most users, `Conda <https://docs.conda.io/projects/conda/en/stable/index.html>`_ is the preferred choice for installing MHKiT-Python. Conda includes the ``conda`` command line utility to manage Python versions and dependencies within `environments <https://business-docs.anaconda.com/en/latest/user/environment.html#:~:text=An%20environment%20is%20a%20folder,from%20other%20collections%20of%20packages.>`_. Anaconda provides a standardized Python build environment that is compatible across operating systems, simplifying MHKiT-Python installation and setup for all users.

pip install mhkit

Using this option to install MHKiT-Python will automatically install Pecos.
1. `Install Conda <https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html>`_ with Anaconda Distribution or Miniconda:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reference the distribution comparison here https://docs.anaconda.com/distro-or-miniconda/


- `Anaconda Distribution <https://docs.anaconda.com/anaconda/install/>`_ is a full featured installer that comes with a suite of packages for data science, as well as Anaconda Navigator, a GUI application for working with conda environments.
- `Miniconda <https://docs.anaconda.com/miniconda/#quick-command-line-install>`_ is a minimal installer provided by Anaconda that installs the ``conda`` command line utility and its dependencies.

Option 2: Clone Repository from GitHub
""""""""""""""""""""""""""""""""""""""""""

This option is recommended for MHKiT-Python developers.
To install MHKiT-Python using `git <https://git-scm.com/>`_::

git clone https://github.com/MHKiT-Software/MHKiT-Python
cd mhkit-python
pip install -e .
2. Access the Conda ``base`` environment:

Using Anaconda Distribution:

- Launch the "Anaconda Navigator" application

- Navigate to the "Environments" section

.. image:: ./figures/install_anaconda_select_environment_section.png
:width: 500
:alt: Navigating to the Anaconda Navigator "Environments" section

- Click the play button next to ``base(root)`` and select "Open Terminal"

.. image:: ./figures/install_anaconda_open_base_environment_terminal.png
:width: 500
:alt: Opening the terminal for the ``mhkit`` environment


Using Miniconda:

- Launch your preferred terminal and execute the following command:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think conda is guaranteed to be active in any terminal (e.g. command prompt). I think we direct users to search for and open the anaconda terminal directly


.. code-block:: bash

conda activate base

3. Download the most recent `MHKiT-Python conda environment file (environment.yml) <https://github.com/MHKiT-Software/MHKiT-Python/blob/master/environment.yml>`_

- Using the terminal

- Execute the following command:

.. code-block:: bash

curl -o mhkit_environment.yml https://raw.githubusercontent.com/MHKiT-Software/MHKiT-Python/master/environment.yml

- Downloading the file manually.


- Navigate to the `MHKiT-Python conda environment file (environment.yml) <https://github.com/MHKiT-Software/MHKiT-Python/blob/master/environment.yml>`_ and download using the "download" button (screenshot below). Move the downloaded file to the current folder in your terminal and rename the file to ``mhkit_environment.yml``

.. image:: ./figures/install_mhkit_python_env_yaml_download.png
:width: 500
:alt: Download MHKiT-Python environment.yml from GitHub

3. Download the most recent `MHKiT-Python conda environment file (environment.yml) <https://github.com/MHKiT-Software/MHKiT-Python/blob/master/environment.yml>`_

- Using the terminal

- Execute the following command:

.. code-block:: bash

curl -o mhkit_environment.yml https://raw.githubusercontent.com/MHKiT-Software/MHKiT-Python/master/environment.yml

- Downloading the file manually

- Navigate to the `MHKiT-Python conda environment file (environment.yml) <https://github.com/MHKiT-Software/MHKiT-Python/blob/master/environment.yml>`_ and use the "download" button to save the file to your local machine. Move the downloaded file to the directory where your terminal is currently open and rename it to ``mhkit_environment.yml``.

.. image:: ./figures/install_mhkit_python_env_yaml_download.png
:width: 500
:alt: Download MHKiT-Python environment.yml from GitHub

Using this option to install MHKiT-Python will require following the `Pecos installation instructions <https://pecos.readthedocs.io/en/latest/installation.html>`_ to install the Pecos package dependency.

4. Create a new environment using the downloaded environment file. In the terminal execute the following command:

.. code-block:: bash

conda env create --name <environment_name> -f mhkit_environment.yml

Replacing ``<environment_name>`` with the desired name for your environment. Common convention is to call the MHKiT-Python environment ``mhkit``.

5. Install MHKiT-Python in the new environment. In the terminal execute the following commands:

.. code-block:: bash

conda activate <environment_name>

.. code-block:: bash

conda install -c conda-forge mhkit

- To run the `MHKiT-Python example notebooks <examples.html>`_ please install the following additional dependencies:

.. code-block:: bash

pip install jupyter notebook folium utm


To verify your MHKiT-Python installation navigate to the `Verifying MHKiT-Python installation <#verifying-mhkit-python-installation>`_ section.

.. Note::
If you plan to contribute to the MHKiT-Python open-source software, please `fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`_ the MHKiT-Python repository into your GitHub user account.
Install MHKiT using Option 2 above.
To include your additions to the MHKiT-Python code, please submit a `pull request <https://github.com/MHKiT-Software/MHKiT-Python/pulls>`_ to the MHKiT-Python develop branch.
Once reviewed by the MHKiT-Python development team, pull requests will be merged into MHKiT-Python and included in future releases.
To use MHKiT-Python in a new terminal activate the environment first by executing::

conda activate <environment_name>

With the anaconda environment activated your terminal prompt should show the environment name in parentheses, indicating that the environment is active. For example, it might look like::

(env_name) user@machine:~$

Test MHKiT-Python installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To test that MHKiT-Python is installed correctly, open a Python console and run::
Option 2: PIP Install from Python
"""""""""""""""""""""""""""""""""

To install MHKiT-Python using `pip <https://pip.pypa.io/en/stable/>`_::

pip install mhkit

.. Note::
The if the ``pip`` installation fails please try the installing MHKiT-Python with Anaconda

Option 3: Clone Repository from GitHub
""""""""""""""""""""""""""""""""""""""

This option is recommended for MHKiT-Python developers. To install MHKiT-Python using `git <https://git-scm.com/>`_::

git clone https://github.com/MHKiT-Software/MHKiT-Python
cd mhkit-python
pip install -e .

Using this option to install MHKiT-Python will require following the `Pecos installation instructions <https://pecos.readthedocs.io/en/latest/installation.html>`_ to install the Pecos package dependency.

.. Note::
If you plan to contribute to the MHKiT-Python open-source software, please `fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`_ the MHKiT-Python repository into your GitHub user account.
Install MHKiT using Option 2 above.
To include your additions to the MHKiT-Python code, please submit a `pull request <https://github.com/MHKiT-Software/MHKiT-Python/pulls>`_ to the MHKiT-Python develop branch.
Once reviewed by the MHKiT-Python development team, pull requests will be merged into MHKiT-Python and included in future releases.

Verifying MHKiT-Python installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To verify that MHKiT-Python is installed correctly, open a Python console and run::

import mhkit

If MHKiT-Python is installed properly, Python proceeds to the next line and no other output is printed to the screen.
If MHKiT-Python is not installed properly, the user will see the following error::
If MHKiT-Python is installed properly, Python proceeds to the next line and no other output is printed to the screen. If MHKiT-Python is not installed properly, the user will see the following error::

ImportError: No module named mhkit

Expand All @@ -75,6 +185,5 @@ To test a simple function using MHKiT-Python, the user can compute the equivalen

The results should be::

ED = 30
AP = 706.8583470577034

ED = 30
AP = 706.8583470577034
5 changes: 3 additions & 2 deletions docs/source/overview.rst
Original file line number Diff line number Diff line change
Expand Up @@ -95,9 +95,10 @@ Developers should run software tests locally before submitting a pull request, u
A summary pdf will be created after running the tests
summarizing the test results.

MHKiT-Python tests using the Python package nose::
MHKiT-Python tests using the Python package pytest::

nosetests -v --with-coverage --cover-package=mhkit mhkit
pip install -r requirements-dev.txt
pytest

MHKiT-MATLAB tests using the MATLAB API::

Expand Down