Bmad Off-Site Release or Conda-Forge Setup

Bmad Off-Site Release Overview

• The Bmad ecosystem consists of the the Bmad library, supporting libraries, and Bmad based programs including Tao.
• Releases can be built on Linux or Mac OS X (intel) computers. For Windows systems, WSL2 should be used.

1. The Bmad source code to build a collection of libraries and executables. (The term " Bmad source code" includes not only the Bmad code library as well as the subsidiary libraries, like cesr_utils, but also the code for programs like Tao.)
2. Script files to build the libraries and executables.

• Linux / Intel ifort compiler (v 17.0.7.259 or later).
• Linux / gcc gfortran compiler (v 6.3 or later).
• Mac Intel / gcc gfortran compiler (v 6.3 or later).

Conda-Forge installation

1. Install the conda package manager according to your platform: https://docs.conda.io/en/latest/miniconda.html
2. Install Bmad via:

   conda install -c conda-forge bmad 

tao

conda search -c conda-forge bmad

conda install -c conda-forge bmad=20211013.0 

conda update -c conda-forge bmad

conda install -c conda-forge bmad="*=mpi_openmpi*"

conda install -c conda-forge compilers  # this will install C, CXX and FC

conda uninstall -c conda-forge bmad

Bmad Release build steps

1. Install the required packages for your operating system and do any required setup
2. Download a Release
3. Set up the Release environment (this step will also need to be executed any time you use Bmad)
4. Compile the Release

Downloading a Release tarball

1. Check compiler requirements for compiling Releases.
2. Download a Release tarball from !GitHub
   The latest Release is recommended.

Installing Packages for Various Operating Systems

• macOS
• RedHat Enterprise Linux and Linux Releases derived from it (CentOS, Scientific Linux)
• Debian Linux and Releases derived from it (Ubuntu)
• Microsoft Windows

• gmake
• automake
• autoconf
• libtool
• m4

• readline
• ncurses
• termcap
• X11 Core and Development Libraries (libX11 and libX11-devel)

• cairo
• pango
• libXt-devel (usually installs as a dependency for cairo/pango)

macOS (formally Mac OS X)

Note: The SHELL for building Bmad is bash.

• If prompted, please don't follow Apple's warning to "upgrade" to zsh.
• If your SHELL set to zsh, please use the command below to switch back to bash:

  chsh -s /bin/bash

Note: There are various Xcode/OS problems. See the Troubleshooting page for details.

The following tools are needed in addition to those listed in the above Libraries and Tools section:

1. XQuartz -- provides core and development libraries for X11 X-Windows graphics support for tao and other packages that require graphical output.
2. Xcode -- Install the latest version from the Apple developer website or get it using the Mac App Store. Once you have Xcode installed, open a terminal, run

    sudo xcode-select --install

   Then click the Install button to install the required command line developer tools.
3. To complete the Apple Xcode License Agreement, please type:

   sudo xcodebuild -license

Setup with MacPorts Package Management System

• The following commands will download the necessary packages

  sudo port install gcc12       # Any version (> 6) of gcc may be used. Except! Use gcc 12 or above with M1 Mac to avoid compiler bug.
  sudo port select gcc mp-gcc12
  sudo port install wget
  sudo port install cmake
  sudo port install gmake
  sudo port install automake
  sudo port install autoconf
  sudo port install libtool
  sudo port install m4
  sudo port install pkgconfig
  sudo port install pango      # Note: Needed for PLplot.
  sudo port install zlib

Setup with Homebrew Package Management System

brew install make
brew install gcc
brew install cmake
brew install automake
brew install autoconf
brew install libtool
brew install pkgconfig
brew install pango
brew install zlib

export CC=gcc-##
export CXX=g++-##

RHEL variants (RHEL, CentOS, Scientific Linux, CERN SLC)

yum install bc cmake gcc-c++ gcc-gfortran libtool make openssl-devel pango-devel readline-devel

yum install centos-release-scl

yum install yum-conf-softwarecollections

yum install cmake devtoolset-12-gcc-gfortran devtoolset-12-gcc-c++ devtoolset-12-make libtool openssl-devel pango-devel readline-devel

scl enable devtoolset-12 bash

Debain Variants (Ubuntu, etc.)

 sudo apt-get install gfortran g++ cmake libtool-bin libreadline-dev libpango1.0-dev libssl-dev bc

sudo apt-get install libxt-dev

MS Windows

1. Install WSL2, which will allow you to run a Linux Release under Windows. For most users the best choice will be to install the latest Ubuntu Release (which is what you will get by default). This may not perform well on a system with a small amount of memory (you're effectively running a second computer on your hardware). Note it is no longer necessary to install an X server, the latest WSL (Windows Store version) has one built-in.
2. Build Bmad as described above on whatever Linux Release you've chosen.

Release Environment Setup

1. Releases are compiled using bash, sh, or ksh. If your default shell is not one of these, you have two options:
   • Switch the default shell to bash (recommended), or
   • Switch to the bash shell each time you want to compile or run using the command

     /bin/bash

2. Users should add the following text to their local account login or profile files (or put these commands in a command file and run the command file each time you create a new command window).
   • Note: Replace PATH-to-Release with the full path to the directory where the Release archive was unpacked.
   • The following stuff should be put in your ~/.bashrc file (or ~/.bash or ~/.profile file whatever one is appropriate):

     export DIST_BASE_DIR="PATH-to-Release"
     source ${DIST_BASE_DIR}/util/dist_source_me
     ulimit -S -c 0
     ulimit -S -s 10240 # Remove this line when using a Mac
     ulimit -d unlimited

     The first ulimit prevents core dump files from being generated (takes up space and no one ever looks at them anyway). The next two ulimit lines helps prevent programs from bombing due to software limits on internal stack and heap sizes.
   • If you are using the multiple Release scheme as discussed above, PATH-to-Release should refer the bmad_dist soft link. For example, the definition of DIST_BASE_DIR might look like:

     export DIST_BASE_DIR="..../Release_base_dir/bmad_dist"

   • Note: The default behavior is for the setup process to print out informational messages. To suppress this output, you may define the environment variable DIST_SETUP_QUIET to have the value "Y". This is entirely optional.
3. If you have put the initalization commands in a shell startup file, setup the environment by simply logging out and logging back in again (and using the /bin/bash command if needed). Otherwise, if not in a shell startup file, source the command file the initialization commands are in.
4. To see information about the Release that is being used by a terminal session, and to make sure the environment is properly setup, use either of the commands:

   distinfo
   accinfo

   Either command will display a summary of the active Release's information, build architecture, selected Fortran compiler and enviromental configuration. In particular, you should see a set of environment variables starting with the prefix ACC_. If you do not see this, the environment has not been properly setup.

Compiling a Release

1. Unzip and extract the tar archive into a working directory of your choice with the command:

   tar -zxf bmad_dist_YYYY_MMDD-N.tgz

2. Set up the Release environment as explained in the Release Environment Setup section. Notice that the environmental variable DIST_BASE_DIR points to the root directory (with a name like to bmad_dist_YYYY_MMDD-N).
3. Change to the root directory:

   cd $DIST_BASE_DIR

4. Edit the file:
   

   $DIST_BASE_DIR/util/dist_prefs

   This file contains the preferences for custimizing the build. Documentation for dist_prefs is contained in the file itself. In particular, one can set:
   • The compiler
   • plotting library back end
   • Whether a shared-object version of the libraries is built. Note: When using the PyTao Python-Tao interface , the shared object version needs to be built.
   • Whether programs that support MPI and/or OpenMP are built multi-threaded.
5. After editing dist_prefs, run your initialization file by loggin out and logging back in again.
6. The final step is to build the source. For building production libraries and executables, type:

   util/dist_build_production

   For building debug libraries and executables, type:

   util/dist_build_debug

• Note: If you ever want to restart the build from scratch, before using one of the build commands above, first remove all compiled files using the command:

  util/dist_clean

Organizing Multiple Releases

              Release_base_dir
                       |
     +--------------------------+------------------------+---------------------+
     |                          |                        |                     |
bmad_dist_2020_0507-0     bmad_dist_2020_0821-0    bmad_dist_2121_0107-0    bmad_dist (soft link)

ln -sfn bmad_dist_2021_0107-0 bmad_dist

Directories in a Release

Directories Containing Executables

Cornell Developed Library Directories:

Cornell Developed Directories containing programs:

Other Cornell Developed Directories:

3rd-Party Libraries ("Packages"):

Building your own code using a Release

Licensing Issues

Issues with building a Release: Troubleshooting Page

Getting Help

Old: Docker Setup