Installing Molflow on Mac

Build from source (2.9+)

You can now also build MolFlow+ from source. The advantage is that it should work regardless of Homebrew package versions. See build instructions in the Gitlab repo.

Install using binaries

To install Molflow on a Mac, you have to go through the following steps:

  • Download and extract Molflow
  • Install Homebrew
  • Get four packages
  • Make Molflow executable
  • Run Molflow

If you just want the instrutions, scroll down, otherwise keep reading

Why does it have to be so difficult?

As a Mac user you're probably used to either the App Store, or ready-built dmg packages where you drag a colorful icon to the Applications folder and just run it. This works with most applications either developed exclusively for Mac, or maintained by larger teams that can afford the effort to develop for the Apple ecosystem.

Molflow runs on Windows, Linux and Mac using exactly the same, standard C++ code. The idea is to ignore built-in package managers, app stores and update mechanisms, and publish exactly the same program for all platforms. That way I don't need to register an Apple developer account, I don't need verification by Apple or digital signatures, and I can provide my own updater mechanism that downloads and installs new versions automatically.

What is Homebrew?

The good news is that Mac OS is a fully Unix-compliant operating system, so in theory anything running on Linux can be ported to it.

The bad news is that many standard tools, like a C compiler, package manager, X11 renderer and other linux stuff are missing from it, because Apple decided that you don't really need them (just use the App Store).

Now, the open source community fixed this by writing Homebrew, a package manager that installs, as the website says, "stuff you need that Apple didn't". Don't be scared of it, it doesn't change the way your Mac works, just downloads and extracts stuff in your /usr/local folder, and it can be uninstalled completely. We'll use it to get some packages that Molflow uses.

What packages does Molflow need?

  • The SDL2 framework that creates an OpenGL context for the main window, captures mouse and keyboard events and handles tasks like copying and pasting from the clipboard
  • LibPNG to load icons and fonts, and to save screenshots in PNG format
  • The GNU Scientific library to generate random numbers
  • The C standard library, included in the GCC package to run modern applicaitons written in C++17
  • The P7Zip project, a MacOS port of 7-zip
  • OpenMP for parallel computing (Molflow versions 2.9+)

Why didn't you just include these packages?

In short, because it would do more harm than good.

See, in Windows, packages can be statically linked (included in the exe file) or dynamically linked (included in a dll file). Windows very rarely makes breaking changes, the last time the binaries were changed was the transition from XP to Vista in 2007. On the other hand, when Molflow became 64-bit in 2014 all libraries had to be changed.

In the unix/linux world, things are different. Mac OS makes major upgrades every year, for example in Mac OS Mojave OpenGL is declared deprecated, and Mac OS 10.15 is expected to drop 32-bit support whatsoever. In the Linux world, many flavors of Linux are not compatible with each other. To save developers from chaos, maintainers of these distributions provide most packages for each version of the operating system, and programs such as Molflow simply reference them. It provides compatibility with future versions, but - as opposed to Windows where you just put some DLLs in the orgram folder - you have to get these packages yourself.

What does it mean to make Molflow executable?

In Windows you can double-click and run exe files.

In Linux and Mac OS, any file, regardless of extension, can be executable. Now this could be a security concern, since one could send you a safe-looking file called bunny.jpg but it would in reality erase all your files or launch a never-ending Monte Carlo simulation :) Therefore you have to explicitly mark files to execute after downloading. You need to do it only once for Molflow (except when the updater gets you a newer version).

Here is what you need to do:

In the instructions below, ignore line breaks, all Terminal commands are to be pasted in a single line.

  • Download the latest Mac version in ZIP format from this site and extract it somewhere. In this example I'll extract it to the Desktop.
  • Open a Terminal and navigate to where Molflow is.
    (Press Command+SPACE to open spotlight, type terminal and press ENTER). Type cd Downloads/molflow_mac_2.9.0 to change to that folder. You can use the TAB key to autocomplete directory names)
    Screen Shot 2018-10-09 at 9.55.15 AM.png
  • Paste and run the following command to install Homebrew:
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    You'll have to type your password and it will take 15-20 seconds to install. In the Mac terminal you can paste with Command+V
  • Paste and run the following to install packages:
    brew install sdl2 libpng gsl gcc p7zip libomp
  • Make Molflow and its 7-zip compressor tools executable:
    • Molflow 2.9+: chmod +x molflow molflowCLI compress

    • Molflow 2.7.9 to 2.8.5: chmod +x molflow molflowSub compress

    • Molflow 2.7.8-: chmod +x molflow compress 7za 
  • That's it! Launch Molflow by typing ./molflow in the terminal, or by opening the Molflow folder in Finder and double-clicking on the molflow file which by now is executable.

This has been tested to work on a Macbook Pro running Mac OS Catalina. Note that on Mac, the ALT key of the Windows/Linux versions has been remapped to the Mac command key, and the mouse wheel was inverted. Report if you run into problems!

Common problems:

macOS security blocking molflow:

When launching ./molflow for the first time, you will likely receive a warning concerning the unverified identity of the developer:

Go to System Preferences -> Security & Privacy -> General and click on Open Anyway:

Afterwards you can run Molflow normally.

In version 2.8 and below, you had to do this separately for molflow and molflowSub. In 2.9+, you need to do it for molflow, then optionally for molflowCLI when you first use it and compress when first trying to save a geo7z file (old format).

Missing libraries

"Symbol not found" or "Library not loaded" error by dyld.

This means that the libraries are newer on your machine than when we compiled molflow. Homebrew doesn't allow to install previous versions of libraries, therefore molflow needs to be recompiled.

  • Ask us to update binaries: If this is the latest macOs and the latest Molflow version (i.e. supported "mainstream" setup), let us know in the forum and we'll compile new binaries quickly that you can download and should run.
  • Build from source: If not, or if you'd like to fix the problem yourself, you can also build molflow from source using the instructions on the Gitlab page. If you run into problems let us know in the forum.
  • Create a symlink: Usually works but not a clean solution: it fools the macOS to load the newer library instead of the old it is looking for. It is likely that there weren't breaking changes and molflow will work.
    • Check which version of the library you have in the same folder. For example, if the error message is 
      dyld: Library not loaded: /usr/local/opt/gsl/lib/libgsl.25.dylib
      then check what you have in that directory:
      ls /usr/local/opt/gsl/lib/libgsl.*.dylib
      note that I have replaced the version number 25 with a wildcard *. This, for example, will give you the installed version:
      /usr/local/opt/gsl/lib/libgsl.27.dylib
      This means that molflow is looking for version 2.5 of the gsl library (because that was the latest when molflow was compiled and uploaded to the website), but meanwhile 2.7 is the latest version, and that's what brew installed for you.
    • Now we have to create a symlink to this newer version, so when macOS looks for libgsl.25.dylib, it will use libgsl.27.dylib:
      ln -s /usr/local/opt/gsl/lib/libgsl.27.dylib /usr/local/opt/gsl/lib/libgsl.25.dylib
    • This creates a symlink called libgsl.25.dylib pointing to libgsl.27.dylib
    • Try to launch molflow

How to uninstall everything:

  • Delete Molflow's folder
  • Uninstall homebrew and its packages following these instructions - current command in Terminal: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"