Installation

There are three types of installations. Basic, which just lets you be a user of Hazelbean (and soon SEALS), Project Installation, and then Developer installation, which gets you up and running with the latest developer repositories. Also check out our video playlist for more context.

1. Basic Installation

Hazelbean is the computational core of the devstack and can be installed using condaforge following these steps. See the Installing Git and Miniforge3 video for a walkthrough.

  1. Install git: https://Git-scm.com/downloads
  2. Install Miniforge3 from https://conda-forge.org/download/
    • Install just for your User Account
    • During installation, select yes for “Add Mambaforge/Miniforge to my PATH environment Variable”
  3. Create a new conda environment, activate it, and then install required packages with the following 3 mamba commands. The third command will take quite a while (10+ minutes). The conda init command may not be needed depending on how you configured your shell.
    1. conda init
    2. conda create -n environment_name
    3. conda activate environment_name
    4. mamba install hazelbean

You can now import hazelbean and it will have precompiled binaries already working for your operating system for geospatial operations using ProjectFlow!

2. Project Installation

If someone has given you a project repository that you want to run and it relies on some combination of our devstack tools, but you are not planning on editing any of the tools, a Project Installation is your best approach. Here we will use seals_cgebox_dev as an example project. See also our video tutorial for Project installation. The project repository should have steps included for installation, but check the seals_cgebox_dev readme.md for an example. Project Installations include a setup_environment.bat or shell file that will setup the environment for you. Note that you need to have a C/C++ compiler installed, so be sure to read that section below.

3. Developer Installation

The Developer Installation installs all (or a subset) of our full devstack. This requires you to have a C/C++ compiler installed (see below). It also specifies canonical file names and structures for where to put the various repositories.

  1. Create a new environment and follow the basic installation steps above.
  2. Remove hazelbean from the new environment with conda remove hazelbean --force. This gets rid of the condaforge version of Hazelbean but keeps its dependencies (NOTE: simple pip uninstalling leaves behind Zombie Folders).
  3. Create the hazelbean Project Folder at C:/Users/<YOUR_USERNAME>/Files/hazelbean/ (PC) or /Users/<YOUR_USERNAME>/Files/hazelbean/ (Mac/Linux)
  4. Clone the desired branch from the hazelbean GitHub repository into your hazelbean Project Folder.
    • git clone -b main https://github.com/jandrewjohnson/hazelbean_dev.git
  5. Navigate to the repo at /Users/<YOUR_USERNAME>/Files/hazelbean/hazelbean_dev/ and then make an editable install of hazelbean with the following command:
    • pip install -e . --no-deps

Add Additional Devstack Repositories as Desired

Now that you have the developer version of hazelbean, you can add additional repositories from our devstack as desired. To do this, using SEALS as an example, follow these steps:

  1. Clone the desired repository, e.g., https://github.com/jandrewjohnson/seals_dev into the proper Project Folder.
    • In the SEALS Project Folder at /Users/<YOUR_USERNAME>/Files/seals/ you will have the Project Repository at /Users/<YOUR_USERNAME>/Files/seals/seals_dev/
    • Navigate to the Project Repsoitory and make an editable install with pip. Make sure you have the right environment activated in your command prompt.
      • pip install -e . --no-deps
  2. Step 1 can be repeated for any of the repositories below (presuming you have read access) - https://github.com/jandrewjohnson/seals_dev - https://github.com/jandrewjohnson/gtap_invest_dev - https://github.com/jandrewjohnson/global_invest_dev - https://github.com/jandrewjohnson/gtappy_dev - https://github.com/jandrewjohnson/gep_dev

Compiling C/C++ Code

Windows:

  • Option 1: You could go to https://visualstudio.microsoft.com/visual-cpp-build-tools/ and select download build tools.

  • Option 2: Enter the following command in the Terminal: winget install Microsoft.VisualStudio.2022.BuildTools --force --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools;includeRecommended" This will launch the build-tools installer (you could do this manually via the MS website if you want, but this ensures you get the right tools).

  • Option 3: Run the install.bat file in the Earth Economy Devestack repo’s root. This just runs the winget command above. - Mac:

Mac/Linux:

  • You can use Xcode to compile the cython files. Most users will already have this installed but if not, follow the directions below.
    • If you don’t have Xcode, you can get it by running xcode-select --install in the Terminal. This command downloads and installs the Xcode Command Line Tools, which includes gcc and clang, the compilers needed to compile C/C++ code on macOS. This is somewhat analogous to the Visual Studio Build Tools on Windows.

Common problems

  • You MUST have administrator rights to your computer.

  • If you’re using Windows PowerShell (instead of the Command Prompt and it isn’t working with Conda, you must initialize conda in powershell)

    • conda init powershell

  • If you don’t add conda to your path, you can do this manually. On PC, you could use the command

    • SETX PATH "%PATH%;C:\Users\<YOUR_USERNAME>\miniforge3;C:\Users\<YOUR_USERNAME>\miniforge3;"
    • (you can do for All Users, but you will need to manually set paths to conda)
      1. If you have an Apple “m1 or m2” chip (a relatively new apple chip, make sure you select the Apple Silicon option). - Install in C:\Users\<YOUR_USERNAME>\miniforge3 (PC) or ~/miniconda3 (Mac)

  • If you get a “Windows Protected your PC”, click more info then Run Anyway.