Getting Started¶

Example Jupyter notebooks¶

Here, we provide Jupyter notebooks for a variety of examples that can be downloaded for interactive use.

Analysis examples¶

Analyze the equilibrium base-pairing properties one or more test tube ensembles (or one or more complex ensembles) — these are the all-purpose sequence analysis tools.

Tube analysis: analyze a test tube ensemble
Multi-tube analysis: analyze a set of test tube ensembles
Complex analysis: analyze a complex ensemble
Multi-complex analysis: analyze a set of complex ensembles

Design examples¶

Design the the sequences for one or more test tube ensembles (or one or more complex ensembles) — these are the all-purpose sequence design tools.

Tube design: design a test tube ensemble
Multi-tube design (simple):
Multi-tube design (advanced):
Complex design: design a complex ensemble

Sample $\LaTeX$ files are provided for the multi-tube design specifications to assist with making new design specs in a standardized format.

Utilities examples¶

Analyze or design a single complex ensemble — these are quick tools applicable when your ensemble is a single complex.

Utilities: analyze or design a complex ensemble

Note

Note that each Jupyter notebook starts by loading the NUPACK Python module:

from nupack import *

Installation requirements¶

NUPACK 4 is a C++ library distributed as a Python package. The following Python packages are required:

Python 3.7-3.11
numpy
scipy
pandas

The following packages are recommended to facilitate interactive usage:

matplotlib
jupyterlab

NUPACK 4 Python packages can be installed for Mac/Linux operating systems or on the Linux subsystem of Windows 10/11. Alternatively, NUPACK may be compiled from source on Mac/Linux.

An easy way to install all of these dependencies is by installing Anaconda.

Mac/Linux installation¶

Warning

Note that for new Macs using an M1 or M2 (arm64) architecture, you must make sure to use a native Python distribution. Separate downloads for the Anaconda or miniconda distributions are available – make sure to choose the distributions labeled “M1”. Importing NUPACK will only function correctly using a native Python distribution. You may use the command

python3 -c "import platform; print(platform.machine())"

to see your installed architecture; this should be arm64 when using an M-series Mac.

Verify your Python installation (make sure you have Python 3.6 or newer):
```
python3 --version
```
If this command does not run, troubleshoot your Python installation. You may not have your $PATH environment variable set correctly.
Update your installation of pip and install the optional dependencies. Run the following commands
```
python3 -m pip install -U pip
python3 -m pip install -U matplotlib jupyterlab
```
Alternatively, if you are using Anaconda, replace the above commands with:
```
conda install --update-all pip matplotlib jupyterlab
```
If this command does not run, troubleshoot your Anaconda installation. You may not have your $PATH environment variable set correctly.
After agreeing to the NUPACK license, download the NUPACK package (e.g., nupack-4.0.0) into your Downloads folder and make sure it is unzipped.
Install the NUPACK 4 Python module by running the following command in your terminal (type y when prompted):
```
python3 -m pip install -U nupack -f ~/Downloads/nupack-VERSION/package
```
Make sure to replace nupack-VERSION with the correct folder name (e.g., nupack-4.0.0).
Check that the correct nupack version is now installed by running the following commmand:
```
python3 -m pip show nupack
```
If the version is not correct, go back to Step 4, double-check the folder name, and rerun the command.

Validate your NUPACK 4 installation by running the following commands:

python3 -m pip install -U pytest
python3 -m pytest -v --pyargs nupack

You can now conveniently run NUPACK 4 jobs as Jupyter notebooks (see above for example notebooks). You can launch a web-based Jupyter notebook browser from the command line:
```
jupyter lab
```
and browse to open your notebook of choice. Click Run->Run All Cells to run the entire notebook. If no browser window appears, try navigating to the displayed link in your terminal. If this doesn’t work, troubleshoot your Jupyter installation.

Windows installation¶

NUPACK may be installed on Windows 10/11 using the Windows Subsystem for Linux 2 (WSL2).

Click the start menu and search for “Windows Features”. Click on “Turn Windows features on or off”. Check the “Windows Subsystem for Linux” icon

Download Ubuntu from the Microsoft Store

Open the Ubuntu app and set a username and password
(Optional) Open the properties window and enable copy paste

Install NUPACK as if using Linux using the following commands (type y when prompted):

mkdir nupack-latest
cd nupack-latest
cp /mnt/c/Users/YOUR-USERNAME/Downloads/nupack-VERSION.zip ./
sudo apt install unzip
unzip nupack-latest.zip
cd ..

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
/bin/bash Miniconda3-latest-Linux-x86_64.sh -b
miniconda3/bin/conda update -n base -c defaults conda
rm Miniconda3-latest-Linux-x86_64.sh

export PATH=$HOME/miniconda3/bin:$PATH
echo 'export PATH=$HOME/miniconda3/bin:$PATH' >> ~/.bashrc

conda install numpy scipy pip matplotlib pandas jupyterlab
pip install -U nupack -f ./nupack-VERSION/package

jupyter lab

Make sure to replace /YOUR-USERNAME/Downloads above with the appropriate directory and nupack-VERSION with the correct version (e.g., nupack-4.0.0).

Use your web browser to open localhost:8888 and use Jupyter Lab to open an example notebook.

Source installation¶

For Mac/Linux users, installation of binaries via pip is by far the easiest option and is strongly recommended. However, if necessary, NUPACK can be built from source.

The following are required:

C++17 compliant compiler (Clang or AppleClang)
CMake

On Mac, it is recommended to use the Clang provided by Homebrew as it is generally kept more up to date than Apple’s builtin version. After installing Homebrew, install Clang via brew install llvm. Then add the flag -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ or -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm/bin/clang++ to your cmake command (use the one corresponding to where brew installed binaries).

Directions:

On a Mac/Linux system, navigate to the source directory within the NUPACK download:

cd ~/Downloads/nupack-VERSION/source

Make sure to replace nupack-VERSION with the correct folder name (e.g., nupack-4.0.0).

Build the included vcpkg submodule using:

./external/vcpkg/bootstrap-vcpkg.sh

or if you are using a Mac and have not previously installed a C++ compiler, using the following flags:

./external/vcpkg/bootstrap-vcpkg.sh --useSystemBinaries --allowAppleClang

Next install the dependencies for NUPACK compilation using vcpkg:

./external/vcpkg/vcpkg install gecode armadillo tbb nlohmann-json jsoncpp taskflow protobuf \
    tclap spdlog fmt boost-context boost-graph boost-align boost-coroutine2 boost-algorithm libsimdpp magic-enum  \
    boost-variant boost-thread boost-sort boost-geometry boost-odeint boost-ublas boost-exception yaml-cpp boost-algorithm

Make a build directory and navigate into it:

mkdir build
cd build

Run the CMake configuration:

cmake .. -DCMAKE_BUILD_TYPE=Release

You may add custom compilation options as flags to the cmake command if desired. Some examples might be:

Add -DCMAKE_CXX_COMPILER=clang++ to use the clang++ compiler. As noted above, compilers besides clang are not generally supported.
Add -DREBIND_PYTHON=/usr/local/bin/python3 to build for a specific Python executable (by default, the python in the user’s $PATH is used).
Add -DCMAKE_CXX_FLAGS="<custom compile options>" to add custom C++ compilation flags.
Add -DCMAKE_POSITION_INDEPENDENT_CODE=ON in the offchance you run into a compilation error asking you to recompile with -fPIC.

Build the C++ code:

cmake --build . --target nupack-python

Install the NUPACK Python module:

pip3 install .