MHKiT-Python Installation

The following sections includes installation instructions for MHKiT-Python.

Requirements

MHKiT-Python requires Python (3.10-3.12). It is recommended to use the Anaconda Python Distribution (a fully featured Python installer with a GUI) or Miniconda (a lightweight installer with the conda command line utility). Both will include most of MHKiT-Python’s package dependencies:

  • Xarray: used for data storage and analysis

  • Pandas: used for data storage and analysis

  • NumPy: used for data storage and analysis

  • SciPy: used for numerical methods, statistics, and signal processing

  • Matplotlib: used to produce figures

  • Requests: used to get data from websites

  • Pecos: used for quality control analysis

Install MHKiT-Python

Option 1: Install from Python

This option is recommended as a fast installation for MHKiT-Python users. To install MHKiT-Python using conda, in an Anaconda Prompt:

conda install -c conda-forge mhkit

Option 2: Clone Repository from GitHub

This option is recommended for MHKiT-Python users who want access to example notebooks and developers. Download and install your preferred version of git. To clone MHKiT-Python:

git clone https://github.com/MHKiT-Software/MHKiT-Python
cd MHKiT-Python

To install a local, editable version of MHKiT-Python using pip:

pip install -e .["all"]

An environment YAML file is also provided that can create the base environment required by MHKiT. MHKiT can then be installed into that environment using any of the provided methods.

Option 3: Module-specific Install from Python

A slim version of MHKiT-Python can be installed to reduce the number of dependencies and potential conflicts with other software. This installation utilizes pip’s optional dependencies installation. To install a single MHKiT module, e.g. the wave module, and its dependencies, use:

pip install mhkit["wave"]

Note that pip install mhkit only installs the base MHKiT dependencies and not the entire software. To install all MHKiT dependencies use:

pip install mhkit["all"]

Note

If you plan to contribute to the MHKiT-Python open-source software, please fork the MHKiT-Python repository into your GitHub user account. Install MHKiT using Option 2 above. Make changes on a feature branch of your personal fork. To include your additions to the MHKiT-Python code, please submit a pull request 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.

Test MHKiT-Python installation

To test 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:

ImportError: No module named mhkit

To test a simple function using MHKiT-Python, the user can compute the equivalent diameter (ED) and projected capture area (AP) of a circular turbine by running the following code:

[ED, AP] = mhkit.river.performance.circular(30)
print(ED)
print(AP)

The results should be:

ED = 30
AP = 706.8583470577034