Masala Core library

Version

Masala's Core library is currently version 1.5.

Description

Project Masala is an open-source successor to the Rosetta software suite, combining the best physics-based, statistics-based, and machine learning-based methods for heteropolymer structure prediction, design, analysis, and modelling.

Masala is divided into a Core library (contained in a Git repository hosted at https://github.com/flatironinstitute/masala_public), and various plugin libraries. The Core library contains minimal infrastructural code, with most of the functionality implemented in plugin libraries. External code may link the Core library at compilation time, and then load and use plugin libraries at runtime, getting the benefit of plugin modules contained in those libraries that were not known at compilation time. This makes things easier for developers, since it allows them to try out new ideas in standalone libraries that can be independently compiled and distributed, as well as for users, who only need to download and compile those libraries that they wish to use, and who do not need to modify or recompile the external software that links Masala's Core library each time a new plugin module is added.

We recommend that, after downloading and compiling Masala's Core library, you consider downloading and compiling the Standard Masala Plugins library, hosted at https://github.com/flatironinstitute/masala_public_standard_plugins. A full list of Masala libraries may be found at https://users.flatironinstitute.org/~vmulligan/.

Authors

The Masala project was started by Vikram K. Mulligan, a Research Scientist in the Center for Computational Biology, at the Flatiron Institute. For questions, e-mail [email protected].

In addition, the following individuals contributed to the development of Masala's Core library:

• Noora Azadvari, a graduate student at the University of Oregon ([email protected]).
• Tristan Zaborniak, a graduate student at the University of Victoria ([email protected]).
• Qiyao Zhu, a Flatiron Research Fellow in the Center for Computational Biology, Flatiron Institute ([email protected]).
• S.M. Bargeen A. Turzo, a Flatiron Research Fellow in the Center for Computational Biology, Flatiron Institute ([email protected]).
• Parisa Hossienzadeh, a professor at the University of Oregon ([email protected]).
• P. Douglas Renfrew, a Research Scientist in the Center for Computational Biology, Flatiron Institute ([email protected]).

Masala is maintained by the Biomolecular Design (BmD) Group in the Center for Computatonal Biology at the Flatiron Institute. Vikram K. Mulligan and P. Douglas Renfrew co-head the group.

Citing Masala

If you use Masala for work that you publish, please cite the following preprint:

T. Zaborniak, N. Azadvari, Q. Zhu, S.M.B.A. Turzo, P. Hosseinzadeh, P.D. Renfrew, and V.K. Mulligan. (2025). The open-source Masala software suite: Facilitating rapid methods development for synthetic heteropolymer design. Methods in Enzymology 723:299-426, doi: 10.1016/bs.mie.2025.09.015. Preprint available from bioRxiv https://www.biorxiv.org/content/10.1101/2025.07.02.662756.

Building

To build the Core Masala library:

1. Clone the git repository (git clone [email protected]:flatironinstitute/masala_dev.git).
2. Clone all of the needed submodules (cd masala_dev && git submodule update --init).
3. Masala is written in C++17. Make sure that your GCC version is 8 or higher. You can check this via gcc --version.
4. Masala's build scripts use nproc to determine the number of cores available for compilation. On newer Macintosh operating systems, it may be necessary to set up an alias for nproc that runs sysctl -n hw.logicalcpu.
5. Run the buildme.sh script.

Note that release mode is the default. To build in debug mode, edit cmake/CMakeLists.txt and change SET( MODE release ) to SET( MODE debug ).

After building, you will likely want to pull and build the Standard Masala Plugins, and possibly the Garam Masala GUI (to be released) or the quantum computing Masala plugins library (to be released).

Updating the build

1. If you are on the main branch, pull the latest changes via git pull. If you are on another branch (you can check via git branch), update your remote branch (git remote update origin --prune).
2. Optionally, delete the previous build (./delete_build.sh). Under most circumstances, this should not be necessary, however: CMake is quite good at only rebuilding parts that need rebuilding, which saves time. But a clean rebuild can be a good idea if the new version that you are compiling is drastically different from old versions.
3. Run the buildme.sh script.

Building Doxygen code documentation

All source code (both manually-written sub-libraries and auto-generated API sub-libraries) is documented with Doxygen tags. To generate Doxygen HTML documentation, first, follow the instructions above to build Masala's Core library. Second, build Doxygen documentation with:

doxygen Doxyfile.src

(Note that Doxygen must be installed.) Documentation will be addded to the html_docs/ directory. Delete this directory to recompile documentation from scratch.

Full Doxygen documentation for the current version of Masala's core is found at https://users.flatironinstitute.org/~vmulligan/doxygen/masala_core_doxygen/index.html.

Using

In order to use Masala, the MASALA_PATH environment variable must be set to the directory in which Masala is installed.

Using Masala as a standalone application

Masala applications can be written that link the Masala libraries, as with any conventional software.

Using Masala through scripting interfaces

PyMasala and MasalaScripts XML interfaces are planned. These will use the Masala API definitions to auto-generate bindings, ensuring a common API to access the same functionality in all languages.

Using Masala through the GUI

The Garam Masala GUI uses the Masala API definitions to auto-generate bindings for Masala modules.

Using Masala as a library

Masala can be used as a C++ library in two ways:

1. By conventionally linking (at compile-time) the Core Masala library plus any needed plugins, and calling code directly. In this case, it is recommended to call code only from the API libraries, since these are the libraries that present a consistent API with guarantees of stability.
2. By conventionally linking (at compile-time) the Core Masala library, and auto-detecting and loading plugin libraries through runtime linking. In this case, plugin objects are accessed entirely through the function pointers in their API descriptions. This has the advantage of allowing a software project to use Masala plugins that were not available at compile time, and to take advantage of new Masala plugins without any recompilation or re-linking (but for runtime linking) needed.

Licence

Masala is released under an AGPL version 3 licence. This licence permits anyone to use the software for any purpose (not-for-profit or commercial), as well as to modify the software and incorporate it into derivative works. The one stipulation is that if any modified version or derivative work is distributed, or users are given access to it over a network, then the source code must be made available under a GPL or AGPL licence (version 3 or later). This ensures that the software remains free and open-source. For full details, see the LICENCE file.

Version history

• Version 1.5: Update buildscripts to remove language feature incompatible with Python older than version 3.9 (tuple type hinting).
• Version 1.4: Minor adjustments to generate_library_api.py for compatibility with the Masala SYCL loop closure plugins.
• Version 1.3: Introduction of the HilbertIndexedMatrix for more efficient searches of data in matrices with fewer cache misses.
• Version 1.2: Small tweak to element names in the ElementType enum class, to avoid name conflicts with "I" (which is often used for identitiy matrices).
• Version 1.1: Small bugfix to RVL optimizer base classes. (A float-float comparison could sometimes fail due to machine precision limits.)
• Version 1.0: Initial non-beta release. Infrastructure for the plugin system, CPU thread management, CFN optimizer base classes, and RVL optimizer base classes fully implemented.