1.1.2. Install on MacOS

1.1.2.1. Install OpenMP

OpenMP is required by the python module pandarm, the routing engine used by R2D’s Residual Demand module for regional transportation network analysis. You need to install OpenMP before installing python. OpenMP is installed via Homebrew by entering the following in a terminal window:

brew install libomp

Note

1. If Homebrew is not yet installed, follow the instructions at brew.sh.

2. To open a terminal window use Spotlight (⌘+Space), type “Terminal” and press your keyboards Enter key.

1.1.2.2. Install Java (JDK 17)

Note

Java is required only if you plan to use the OpenSHA-based regional seismic hazard feature in R2D app (Earthquake Event Simulation). If you do not need this feature, you can skip this section.

R2D app is tested with Eclipse Temurin JDK 17, the long-term-support (LTS) build of Java. We recommend this exact version.

Which installer should I download?

The right installer depends on your Mac’s processor, because Java must match the architecture of the Python you installed earlier:

• Apple Silicon Mac (chips named M1, M2, M3, or M4 – any Mac sold since late 2020): download the macOS aarch64 installer from Temurin JDK 17 — macOS Apple Silicon (aarch64).

• Intel Mac (any Mac sold before late 2020): download the macOS x64 installer from Temurin JDK 17 — macOS x64.

To check which kind of Mac you have, click the Apple menu in the top-left corner of your screen and choose About This Mac. Look at the Chip (or Processor) line: if it starts with “Apple” you want the aarch64 installer; if it says “Intel” you want the x64 installer.

To install:

1. Click the matching link above. On the Adoptium page, click the download icon next to the PKG option to download the .pkg file. You’ll get a file named something like OpenJDK17U-jdk_aarch64_mac_hotspot_17.0.X_Y.pkg (or ...x64... for Intel).

2. Once the download finishes, double-click the .pkg file in your Downloads folder. The macOS installer will open. Accept the defaults on each screen and click Install at the end. You may be asked for your password.

Tip

If you already have a different Java version installed on your Mac, you do not need to remove it. Multiple Java versions coexist without conflict – each lives in its own folder under /Library/Java/JavaVirtualMachines/.

Note

The Java website should automatically detect and suggest the appropriate installer for your operating system.

1.1.2.3. Install Python

The R2D app requires Python be installed on your machine and that the version of it be in the 3.10 – 3.12 range.

To check what you have, open Terminal (Spotlight: ⌘+Space, type “Terminal”, press Enter) and run:

python3 --version

If it reports a 3.10, 3.11, or 3.12 number, you’re set and can go to the next step. If not, you need to install an appropriate version. We recommend 3.12.

To Install Python 3.12

1. Go to the tool download page (link: R2D Download). On the browser page that this brings up, you will find various files and directories available for download. Locate the file named python-3.12.6-macosx11.pkg, which we copied from Python.org. Proceed to download this installer file.

2. Locate this installer file in your Downloads folder, and double click on it to start the installation process. Upon completion, a folder with several files will open, as shown in the figure below. Execute Update Shell Profile.command.sh and Install CertificateCommand.sh by double-clicking each.

3. Click on this link -> R2D Download. On the browser page that this brings up, you will find various files and directories available for download. Locate the file named python-3.12.X-macos11.pkg (where X is the latest patch number), which we copied from Python.org. Proceed to download this installer file.

4. Locate this installer file on your system and double click on it to start the installation process. Upon completion, a folder with several files will open, as shown in the figure below. Execute Update Shell Profile.command and Install Certificates.command by double-clicking each.

   

   Fig. 1.1.2.3.1 Python: Folder Displayed at Conclusion of Install

5. Repeat the first python version check above in a NEW terminal window.

Note

If you still have the incorrect version of python installed after following the above steps, it probably means you forgot to invoke the Update Shell Profile Command.command script. You can still do it using Finder. Open Finder and navigate to the /Applications/Python 3.12 folder. Here you will see a number of files, including the two you forgot to run: Install Certificates Command.command and Update Shell Profile Command.command. Double click on these files to run them. Finally open a NEW terminal again and check your version of python.

1.1.2.4. Optional: Create a Python Environment

If you have a current version of Python that meets the requirements (3.10, 3.11 or 3.12) and want to re-use it, or if you will be using additional SimCenter applications, we strongly recommend creating a python virtual environment. This is in case the python modules wou will install in next step don’t mix with your current ones or ones you will need in the future. To create a python environment for R2D app and then switch to that environment, issue the following in the terminal window:

cd ~
mkdir python_env
cd python_env
python3 -m venv python-R2D
source ./python-R2D/bin/activate

Note

These commands create a folder in your home directory named python_env, instruct the current default python interpreter to create a directory for a virtual environment named python-{short tool id| in this folder, and from the many files in this new folder that are present, you invoke a script activate that sets up the terminal environment such that it uses the python interpreter you created the environment with and, most importantly, will install python packages into this folder.

1.1.2.5. Install Python Modules

In the terminal window you have opened, you need to issue the following 2 commands to ensure the command line tools for x-code exist on your machine and that some python modules are installed for the current python you are using:

xcode-select --install
python3 -m pip install --upgrade "nheri_simcenter[r2d]"

1.1.2.6. Note Your Python Path

R2D app needs the full path to the Python interpreter. Find it with the which command in Terminal.

which python3

If you are using the newly installed python without a virtual environment you should see: /Library/Frameworks/Python.framework/Versions/3.12/bin/python3. If using a python environment you willl instead see: /Users/YOUR_LOGIN/python_env/python-R2D/bin/python3. Copy this path to your clipboard.

Note

When the application is actually running, you will need to change the location of the python application that will run if you are using a virtual environment or if the existing python interpreter you are using is in a different location. To do this, in the top menu bar, under the tool icon select Preferences (on some macOS versions it is Settings). Change the location of python, the first variable you can edit, to the python3 path noted, e.g. /Users/YOUR_LOGIN/python_env/python-R2D/bin/python3. Finally press the Save button. Please note that YOUR_LOGIN needs to be replaced with your actual login!

1.1.2.9. Download the Application

To download the R2D app, navigate to the R2D Download page which should resemble Fig. 1.1.2.9.1. The download page contains a list of downloadable files and directories. Two macOS build are listed |tool app id|_MacOS_Download_arm64.dmg, for Apple Silicon Macs (chips named M1, M2, M3, **M4*, and M5) and |tool app id|_Mac_Download_x86_64.dmg for older INtel-based Macs.

Note

To check which you have: click the Apple menu in the top-left corner of your screen and choose About This Mac. Look at the Chip (o**Processor**) line. If it starts with “Apple”, you want the arm64 download. If it says “Intel”, you want the x86_64 download. If you pick the arm64 build on an Apple Silicon Mac, R2D runs natively and is significantly faster than under emulation. The arm64 build will not run on an Intel based Mac.

Fig. 1.1.2.9.1 R2D Tool download page.

Click on the appropriate file link in the pop-up window, then click on the Download button in the bottom right corner. After the download is completed, open the dmg file and copy the R2D to a location in your filesystem.

Note

We suggest copying the application either the Applications folder or your Desktop. After copying the application, you can move the dmg file to the trash or eject it.

1.1.2.10. Test the Installation

Once the installation procedure has been completed, it is a good practice to run some basic checks. Navigate to the location where you placed the application and open it by double-clicking the R2D application.

Note

SimCenter apps are code-signed and notarized, but because they are not downloaded from the Apple app store, they will not be recognized as safe applications. Depending on your security settings, when you start a SimCenter app for the first time, your operating system may show a dialog box indicating it is unsafe. If this dialog appears, choose the cancel button. Try to start the app again, this time by right-clicking on it and selecting open.

If the app still fails to open. You need to go to System Settings->Privacy and Security. Under the Security section, you need to at least temporarily select the option to allow applications downloaded from the App Store and Identified Developers. With this checked try again. If it fails again, go back to System Settings->Privacy and Security. Just below the section you just checked, there should be some text about why the app was stopped and an option to Open Anyway, as shown in the figure below. Click on the button and the app should start.

Once the application starts, verify the setup by running an example problem r2dt-0006, see Fig. 1.1.2.10.1.

Fig. 1.1.2.10.1 R2D Tool on startup.

Note

When the R2D app is running, open the app/preferences or File/Preferences and make sure that python3 appears under External Applications:Python, as shown in the figure below. If you used older versions of SimCenter tools this was not the default. The exact location of Python3 that you installed can be found by opening the terminal application and executing the which python3 command. Enter the path shown as a response in the Preferences panel under Python and then press the Save button.

Fig. 1.1.2.10.7 Set Python Preferences.