1.4. Setting up CODAS packages

If you installed a Virtual Computer, you do not need to follow these steps; they have already been done.

For Install Option #2 (conda) or Option #3 (Ubuntu) you will:

1.4.1. Download CODAS software using Mercurial

This is the first of four steps to install the CODAS software on the computer built using earlier sections of this documentation.

Note

If you are running the pre-built virtual computer, you can skip this step. It is already done.

Mercurial is a distributed version control system. We use it to store and track changes in CODAS software. With any of the options (1,2,3) for installation, Mercurial should already be installed.

Make a location for CODAS software

We will put downloaded code and documentation in the following subdirectories of the user’s home directory:

  • ~/adcpcode/programs (for these mercurial repositories and a few zip archives)

  • ~/adcpcode/topog (for topography)

To make this structure, execute:

mkdir ~/adcpcode
mkdir ~/adcpcode/programs
mkdir ~/adcpcode/topog

Use Mercurial to download our code, along with its history:

cd ~/adcpcode/programs
hg clone   https://currents.soest.hawaii.edu/hg/codas3
hg clone   https://currents.soest.hawaii.edu/hg/pycurrents
hg clone   https://currents.soest.hawaii.edu/hg/onship
hg clone   https://currents.soest.hawaii.edu/hg/uhdas

Now you are ready to compile and install CODAS components.

(Return to TOP)

1.4.2. Compile and install CODAS components

Note

If you are using a prebuilt Virtual Computer, you can skip this step

At this point, you should have a working Python environment, either via conda or via the installation of packages from your Linux distribution, and you have used Mercurial to clone our repositories into ~/adcpcode/programs.

Check your Python environment. If you are using conda, your prompt should include (pycodas); if it doesn’t, execute conda activate pycodas. You can also check your python version:

python --version

should return something like:

Python 3.9.1

The version number will depend on when and how you installed or last updated Python.

In the following, steps will be given first for the case of conda-based installations, then for Ubuntu native installations, where administrative privileges are needed for some operations, and obtained using sudo.

Compile and install codas3 (C code for libraries and executables) first.

For a conda-based installation:

cd ~/adcpcode/programs/codas3
./waf configure --python_env
./waf build
./waf install
cd ~

The --python_env option for the conda case will install to standard locations in the pycodas environment within your home directory tree, so no administrative permissions are required.

For Ubuntu native:

cd ~/adcpcode/programs/codas3
./waf configure
./waf build
sudo ./waf install
cd ~

For the Ubuntu native case, everything is installed in standard subdirectories of the default, /usr/local, requiring the use of sudo for the installation operation. Check that /usr/local/bin is on your PATH environment variable; if it isn’t, add it now before proceeding because the next step depends on it.

Compile the C extension code in the pycurrents package, and install it along with the uhdas and onship packages. Most of the CODAS processing tools are in pycurrents.

For the conda-based installation:

cd ~/adcpcode/programs/pycurrents
python ./runsetup.py
cd ../uhdas
python runsetup.py
cd ../onship
python setup.py install
cd ~

For Ubuntu native:

cd ~/adcpcode/programs/pycurrents
python3 ./runsetup.py --sudo
cd ../uhdas
python3 runsetup.py --sudo
cd ../onship
python3 setup.py build
sudo python3 setup.py install
cd ~

Note

The uhdas installation here is only for obtaining access to code used in processing data acquired with UHDAS. It does not constitute the UHDAS system itself.

Now that you have compiled and installed CODAS C and Python code, it is time for the next step: getting the non-Mercurial components.

(Return to TOP)

1.4.3. Download documentation and processing demo directories

Note

If you are using a prebuilt Virtual Computer, you can skip this step

The components to be downloaded are zip archives served from https://currents.soest.hawaii.edu/docs/zipped. The most reliable way to download them is by using the curl utility which is available by default on MacOS. You can probably right-click on the items and select “download”, but they may not land where you want them to be. Follow the instructions below for a consistent result.

On Linux, if you don’t have it yet, install it with:

sudo apt install curl

To download and install everything in the appropriate location, execute:

cd ~/adcpcode/programs
curl -O https://currents.soest.hawaii.edu/docs/zipped/adcp_doc.zip
unzip adcp_doc.zip
curl -O https://currents.soest.hawaii.edu/docs/zipped/adcp_py3demos.zip
unzip adcp_py3demos.zip

The first of these contains the same documentation you are reading now:

zip archive

subdirectory

contents

DOCUMENTATION

adcp_doc.zip

adcp_doc

  • same contents as on WWW

The second contains tutorial and demo material:

zip archive

subdirectory

contents

DEMO PROCESSING

adcp_py3demos_proc.zip

adcp_py3demos/adcp_pyproc

  • Python3 CODAS Processing Tutorials

adcp_py3demos/uhdas_data

  • UHDAS data

adcp_py3demos/vmdas_data

  • VmDAS data

Your adcp_py3demos directory structure should look like this after unpacking:

adcp_py3demos directory structure

The fourth and final step in getting CODAS processing to work, is to download suitable topography.

(Return to TOP)

1.4.4. Download and install Topography files

Note

If you are using a prebuilt Virtual Computer, you can skip this step

For processing, editing, and visualization we need topography data; we will use Etopo1. As for the documentation and demo data, we will use curl to download it:

cd ~/adcpcode/topog
mkdir etopo
cd etopo
curl -O ftp://currents.soest.hawaii.edu/pub/outgoing/etopo1_for_pycurrents.zip
unzip etopo1_for_pycurrents.zip

We will install this in a location where the pycurrents code that uses it can find it, but instead of moving the directory we will just point to it with a symbolic link. That location differs between conda and Linux native installations, so:

With conda:

cd ~/miniconda3
ln -s ~/adcpcode/topog .
cd

For Linux native:

cd /usr/local
sudo ln -s  ~/adcpcode/topog .
cd

(Return to TOP)

1.4.5. Install the “toml” library

Note

If you are using a prebuilt Virtual Computer, you can skip this step

Note

If you are using a using a miniconda environment, you can skip this step

We are working towards storing the configuration information in a different language than Python. We will be using “toml”. Install the toml library:

sudo pip3 install toml

That’s it. Everything should now be in its proper place, ready for a test.

(Return to TOP)