The Masala Seating Optimization Plugins library is currently version 1.0.
Plugins for the Masala software suite that allow Masala to optimize seating arrangements at events like weddings, using Masala classical or quantum optimizers. This is useful in three ways. First this repository provides means of solving these hard problems. Second, it serves to demonstrate Masala's use for optimization problems very different from (but related to) the peptide and protein design problems for which Masala was developed: the code patterns that run configure and run plugin optimizers may be emulated by those wishing to apply these tools to their own problems. And third, this repository provides benchmarks to test existing and future Masala CFN optimizers.
The Masala Seating Optimization Plugins library must be linked against the Masala Core library, available from https://github.com/flatironinstitute/masala_public. It can load plugin optimizers found in the Standard Masala Plugins library, available from https://github.com/flatironinstitute/masala_public_standard_plugins](https://github.com/flatironinstitute/masala_public_standard_plugins), or from the Quantum Computing Masala Plugins library, which will be released publicly in the near future.
- Vikram K. Mulligan, Research Scientist, Co-head of Biomolecular Design Group, Center for Computational Biology, Flatiron Institute (vmulligan@flatironinstitute.org).
- Karie A. Nicholas, Director of Evaluation and Impact, Foudantion for Health Care Quality (knicholas@qualityhealth.org).
- Compile Masala using the buildme.sh script in the masala/ directory.
- Set up a simlink to the headers/masala/headers directory. For instance:
ln -s ~/my_projects/masala/headers/ ~/my_projects/seating_optimization_masala_plugins/headers/masala/ - Set up simlinks to the dylib files or so files in your masala build directory. For instance
cd ~/myprojects/seating_optimization_masala_plugins/lib && ln -s ~/my_projects/masala/build/lib* . - Set up a simlink to the external/ directory. For instance:
ln -s ~/my_projects/masala/external ~/my_projects/seating_optimization_masala_plugins/ - Set up a simlink to the code_templates/ directory. For instance:
ln -s ~/my_projects/masala/code_templates ~/my_projects/seating_optimization_masala_plugins/ - Run the buildme.sh script (
./buildme.sh) to compile and link the Masala seating optimization plugin library.
- Note that default compilation is in release mode.
- To compile in debug mode, edit cmake/CMakeLists.txt and change
SET( MODE release )toSET( MODE debug ).
To run unit tests, use the following commands after compiling:
./build/seating_optimization_tests
./build/registration_tests
Note that some tests require the following environment variables to be set:
MASALA_PATH: This should point to your core Masala repository's build/ directory.
MASALA_STANDARD_PLUGINS: This should point to the (top-level) directory that countains the Masala standard plugins repository.
MASALA_SEATING_OPTIMIZATION_PLUGINS: This should point to the top-level directory containing this repository.
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 and the Masala Seating Optimization Plugins 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.
Doxygen documentation for the current version of this repository is available from https://users.flatironinstitute.org/~vmulligan/doxygen/masala_seating_optimization_plugins_doxygen/index.html.
The bin/optimize_seating application runs seating optimization problems using an available Masala CFN optimizer. To see the list of available options, run ./bin/optimize_seating -h. This currently produces the following output:
Starting optimize_seating application.
Application created 15 August 2025 by Vikram K. Mulligan, Biomolecular Design Group, Center for Computational Biology, Flatiron Institute, in collaboration with Karie A. Nicholas, Foundation for Health Care Quality.
Please write to vmulligan@flatironinstitute.org for questions.
Parsed -h option.
The following options may be set:
-approximate_binary_extra_qubits If the approximate binary data representation is used, this is the number of extra qubits to use. Default 0.
-classical_attempts_per_problem The number of attempts (Monte Carlo trajectories) that classical optimizers, such as the MonteCarloCostFunctionNetworkOptimizer or the HillFlatteningMonteCarloCostFunctionNetworkOptimizer, will run. Defaults to 1 if not specified.
-classical_mc_steps The number of Monte Carlo steps per attempt that classical optimizers, such as the MonteCarloCostFunctionNetworkOptimizer or the HillFlatteningMonteCarloCostFunctionNetworkOptimizer, will make. Defaults to 1,000,000 if not specified.
-do_greedy Should solutions be greedily refined? This is an option for all optimizers; must be TRUE or FALSE. Defaults to TRUE.
-dwave_annealing_time The D-wave annealing time, in microseconds. Defaults to 20.0
-dwave_mapping_type The D-Wave mapping type to use. Only used if the D-Wave is used. Allowed mappings include: ApproximateBinaryQUBOProblem, DomainWallQUBOProblem, OneHotQUBOProblem.
-dwave_onenode_penalty_cap The cap on the one-node penalty values. Only used to limit dynamic range if the D-Wave is used. Defaults to 100.0.
-dwave_samples The number of samples for the D-Wave to perform. Defaults to 1000.
-dwave_solver_name The name of the solver. Required input if the D-Wave is used.
-dwave_twonode_penalty_cap The cap on the two-node penalty values. Only used to limit dynamic range if the D-Wave is used. Defaults to 100.0.
-dwave_use_inhomogeneous_driving Should inhomogeneous driving be used? Default true. Only used if the D-Wave is used.
-dwave_use_layout_embedding If true, we use Layout embedding; if false, we use MinorMiner embedding. Defaults to false.
-flattening_boltzmann_temperature The Boltzmann temperature to use for flattening the solution score landscape, if the HillFlatteningMonteCarloCostFunctionNetworkOptimizer is used. Defaults to 10.0.
-h Print a help message and exit.
-help Print a help message and exit.
-masala_plugins The paths to the masala plugins that will be loaded, as a comma-separated list.
-optimizer_name The name of the optimizer to use to solve the seating optimization problem. Currently supported optimizers include: HillFlatteningMonteCarloCostFunctionNetworkOptimizer, MonteCarloCostFunctionNetworkOptimizer, DWaveQuantumQUBOProblemOptimizer.
-problem_file The name (with absolute or relative path) of the file defining the seating optimization problem to solve. Required input.
-solutions_to_store_per_problem The maximum number of solutions to return, for any optimizer. Defaults to 1.
-total_threads The number of threads to launch. Defaults to 1. Zero means to launch one thread per CPU core on the node.
Example input files are in the test_data subdirectory. Input files allow users to define a seating optimization problem, which consists of the following seating optimization elements:
- The Room defines the space in which tables are laid out. It is intended for visualization purposes.
- Seats hold Guests. They are arranged around Tables.
- Guests are the people who must be seated.
- Restraints limit particular guests to certain seats. They simplify the optimization problem by eliminating certain assignments completely.
- Constraints give bonuses or penalties for seating guests in certain seats, or pairs of guests in certain seats in relation to one another.
More information on the syntax for defining each of these is found below.
The Room class is a pure virtual base class. Derived classes define rooms of particular shapes. Currently, the only shape implemented is a rectangular room, implemented in the RectangularRoom class. The syntax for defining a RectangularRoom is as follows:
RectangularRoom <CENTRE_X> <CENTRE_Y> <ANGLE_DEGREES> <LENGTH> <WIDTH>
For instance, to define a room centred at (1.5,2.3), with a length (y dimension) of 5 meters and a width (x dimension) of 9 meters, rotated by 10 degrees clockwise, one would write the following:
RectangularRoom 1.5 2.3 10.0 5.0 9.0
Only a single Room may be defined for a given seating optimization problem.
The Table class is a pure virtual base class. Derived classes define tables of particular shapes. Currently, only the CircularTable class is implemented, with input syntax as follows:
CircularTable <CENTRE_X> <CENTRE_Y> <ANGLE_DEGREES> <RADIUS> <SEAT_COUNT> <OPTIONAL_SEAT_LOCAL_INDEX_TO_OMIT_1> <OPTIONAL_SEAT_LOCAL_INDEX_TO_OMIT_2> <OPTIONAL_SEAT_LOCAL_INDEX_TO_OMIT_3> ...
Although the table itself is circular, it may be rotated to shift the seats around. In the unrotated case, seats are numbered from the top, clockwise around the table. Rotation shifts the seats clockwise. As an example, the following defines a circular table with four seats, located at (1.0, -1.0), with a radius of 1.5 meters, and with four evenly-spaced seats, the southernmost of which is omitted, and with all seats rotated 15 degrees clockwise:
CircularTable 1.0 -1.0 15.0 1.5 4 2
Note that the local indices of the seats around the table are, clockwise from the northernmost, 0, 1, 2 and 3. The arguments for omitting seats are optional: by default, no seats are omitted.
Standalone Seat objects, with no associated Table, may also be defined using the following syntax:
Seat <CENTRE_X> <CENTRE_Y> <ANGLE_DEGREES>
A seating optimization problem may have as many tables and seats as the user wishes. Each guest will be assigned one seat, which means that if there are more seats than there are guests, some seats will remain unassigned.
A seating optimization problem must have at least one Guest (and a nontrivial problem will have many). A Guest is a person who must be assigned a seat. Note that the name "guest" is not meant to imply a relationship to the event: in the case of wedding seating optimization, the bride(s) and/or the groom(s) are considered "guests" along with all the people whom they invite to their wedding.
A Guest must be assigned a short name string containing no whitespace, used for subsequent setup of constraints, and a full name that may contain whitespace, used for user-facing outputs. The syntax for defining a Guest is:
Guest <SHORT_GUEST_NAMESTRING> <FULL_NAME_1> <FULL_NAME_2> <FULL_NAME_3> ...
For instance, to define a guest named "John Jacob Jingleheimer Schmidt", we would write:
Guest jjj_schmidt John Jacob Jingleheimer Schmidt
A seating optimization problem may have any number of guests. Note that if there are more guests than seats, some seats will inevitably be occupied by more than one guest, so a sensible problem has at least as many seats as guests.
A Restraint is are hard prohibitions on assigning a particular seat to a particular guest. Since that particular seat assignment isn't even considered, a Restraint simplifies the problem, making it easier for a solver to optimize. The Restraint class is a pure virtual base class with two derived classes: RestrictGuestToSeatsRestraint (which prohibits consideration of any seat but for those listed for a particular guest) and RestrictGuestToTableRestraint (which prohibits consideration of any seat but those at the table indicated for a particular guest).
Any number of restraints may be defined for a seating optimization problem.
The syntax for a RestrictGuestToSeatsRestraint is:
RestrictGuestToSeatsRestraint <SHORT_GUEST_NAMESTRING> <SEAT_GLOBAL_INDEX_1> <OPTIONAL_SEAT_GLOBAL_INDEX_2> <OPTIONAL_SEAT_GLOBAL_INDEX_3> ...
Global seat indices are zero-based and based on the order in which seats or tables were defined. The short guest namestring must have previously been defined as part of a Guest setup line.
The syntax for a RestrictGuestToTableRestraint is:
RestrictGuestToTableRestraint <SHORT_GUEST_NAMESTRING> <TABLE_INDEX>
The table index is zero-based (matching the order in which tables were defined), and as before, the short guest namestring must have previously been defined as part of a Guest setup line.
Unlike a Restraint, which simplifies the problem, a Constraint in no way reduces the number of combinatorial permutations that will be considered. Instead, a Constraint simply defines a bonus or a penalty for particular seat assignments or seat assignment combinations. The Constraint base class is pure virtual. Derived classes include the GuestOverlapConstraint (which discourages multiple guests from being assigned to the same seat), the GuestPairAdjacentSeatConstraint (which encourages or discourages a particular pair of guests to be seated next to one another), the GuestPairSameTableConstraint (which encourages or discourages a particular pair of guests to be seated at the same table), and the GuestPairProximityConstraint (which encourages or discourages a particular pair of guests to be seated near one another in physical space).
Any number of constraints may be defined for a seating optimization problem.
A GuestOverlapConstraint should be defined for just about any seating optimization problem, since it is almost always undesirable to have guests sitting on one another's laps -- or, at least, the optimization problem that must be solved for that sort of get-together is outside of the scope of this project. The GuestOverlapConstraint provides a constant penalty for any two guests being assigned to the same seat. Its syntax is:
GuestOverlapConstraint <CONSTRAINT_STRENGTH>
The constraint strength should be set to a positive value to discourage duplicate assignments. Since this applies globally to all guests and to all seats, there is no need to provide any additional information. Although there is nothing preventing multiple guest overlap constraints from being defined, since they are additive, the effect would be no different than adding a single guest overlap constraint with a penalty value that was the sum of the penalty values of the several guest overlap constraints.
A GuestPairAdjacentSeatConstraint provides a bonus (negative value) or penalty (positive value) if a particular pair of guests is seated at any pair of adjacent seats. The syntax is:
GuestPairAdjacentSeatConstraint <SHORT_GUEST_1_NAMESTRING> <SHORT_GUEST_2_NAMESTRING> <BONUS_OR_PENALTY_VALUE>
The short guest namestrings must have been defined previously in Guest lines.
A GuestPairSameTableConstraint provides a bonus (negative value) or penalty (positive value) if a particular pair of guests is seated at any two seats at the same table, for any of the tables that have been defined. The syntax is:
GuestPairSameTableConstraint <SHORT_GUEST_1_NAMESTRING> <SHORT_GUEST_2_NAMESTRING> <BONUS_OR_PENALTY_VALUE>
Again, the short guest namestrings must have been defined previously in Guest lines.
A GuestPairProximityConstraint provides a bonus (negative value) or penalty (positive value) if a particular pair of guests is seated nearby in space, whether or not they are at the same table or in adjacent seats. It requires the definition of a distance function used to scale the constraint strength; currently the only falloff function that is implemented is the GAUSSIAN function. The syntax is:
GuestPairProximityConstraint <SHORT_GUEST_1_NAMESTRING> <SHORT_GUEST_2_NAMESTRING> <BONUS_OR_PENALTY_VALUE_AT_ONE_UNIT_DISTANCE> GAUSSIAN <GAUSSIAN_STANDARD_DEVIATION>
Once again, the short guest namestrings must have been defined previously in Guest lines.
If you use this software, please cite:
K.A. Nicholas and V.K. Mulligan. (2026). "Entangled happily ever after: Wedding reception seating mapped to classical and quantum optimizers". Manuscript under review. Preprint available from arXiv: https://arxiv.org/abs/2604.10497.