Installation#

This document describes how to install CapyMOA and its dependencies. CapyMOA is tested against Python 3.10, 3.11, and 3.12. Newer versions of Python will likely work but have yet to be tested.

Virtual Environment (Optional)

We recommend using a virtual environment to manage your Python environment. Miniconda is a good choice for managing Python environments. You can install Miniconda from here. Once you have Miniconda installed, you can create a new environment with:
```
conda create -n capymoa python=3.11
conda activate capymoa
```
When your environment is activated, you can install CapyMOA by following the instructions below.
Java (Required)

CapyMOA requires Java to be installed and accessible in your environment. You can check if Java is installed by running the following command in your terminal:
```
java -version
```
If Java is not installed, you can download OpenJDK (Open Java Development Kit) from this link, or alternatively the Oracle JDK from this link. Linux users can also install OpenJDK using their distribution’s package manager.

Now that Java is installed, you should see an output similar to the following when you run the command java -version:
```
openjdk version "17.0.9" 2023-10-17
OpenJDK Runtime Environment (build 17.0.9+8)
OpenJDK 64-Bit Server VM (build 17.0.9+8, mixed mode)
```
PyTorch (Required)

The CapyMOA algorithms using deep learning require PyTorch. It is not installed by default because different versions are required for different hardware. If you want to use these algorithms, follow the instructions here to get the correct version for your hardware. Ensure that you install PyTorch in the same environment virtual environment where you want to install CapyMOA.

For CPU only, you can install PyTorch with:
```
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
```

Install CapyMOA

pip install capymoa

To verify your installation, run:

python -c "import capymoa; print(capymoa.__version__)"

Install CapyMOA for Development#

If you want to make changes to CapyMOA, you should follow these steps to set up an editable installation of CapyMOA, with development and documentation dependencies.

Dependencies

Follow the instructions above to install PyTorch, Java, and optionally a virtual environment.
Pandoc

Ensure that you have Pandoc installed on your system. If it’s not installed, you can install it by running the following command on
Ubuntu
sudo apt-get install -y pandoc
macOS
sudo brew install pandoc
Window/Other

Follow the instructions on the Pandoc website.

conda
conda install -c conda-forge pandoc
Clone the Repository

If you want to contribute to CapyMOA, you should clone the repository, install development dependencies, and install CapyMOA in editable mode.

If you are intending to contribute to CapyMOA, consider making a fork of the repository and cloning your fork instead of the main repository. This way, you can push changes to your fork and create pull requests to the main repository.
```
git clone https://github.com/adaptive-machine-learning/CapyMOA.git
# or clone via the SSH protocol (often preferred if you use SSH keys for git):
#   ``git clone with git@github.com:adaptive-machine-learning/CapyMOA.git``
```
Install CapyMOA in Editable Mode

To install CapyMOA in editable mode with development and documentation dependencies, navigate to the root of the repository and run:
```
cd CapyMOA
pip install --editable ".[dev,doc]"
```

Congratulations!

You have successfully installed CapyMOA in editable mode.

A number of utility scripts are defined in tasks.py to perform common tasks. You can list all available tasks by running:

python -m invoke --list # or `invoke --list`

Available tasks:

  commit               Commit changes using conventional commits.
  refresh-moa          Replace the moa.jar file with the appropriate version.
  build.clean          Clean all build artifacts.
  build.clean-moa      Remove the moa.jar file.
  build.clean-stubs    Remove the Java stubs.
  build.download-moa   Download moa.jar from the web.
  build.stubs          Build Java stubs using stubgenj.
  docs.build           Build the documentation using Sphinx.
  docs.clean           Remove the built documentation.
  docs.coverage        Check the coverage of the documentation.
  test.all (test)      Run all the tests.
  test.nb              Run the notebooks and check for errors.
  test.unit            Run the tests using pytest.

See the Contributing guide for more information on how to contribute to CapyMOA.