class scm.reactmap.Settings(**kwargs)

This is the main class for inputting settings for solving the problem(s).

Table 1 General problem solving options




  • True (default) - Treat all hydrogens as implicit. This greatly reduces the dimension of the optimization problem and can lead to significant performance gains. Note that these constraints assume all Hydrogens are bound to at most one other atom.

  • False - Do not use an implicit Hydrogen representation of the problem.


These options allow the user to choose between MIP formulations.
  • ‘bondmapping’ - use a larger MIP formulation that explicitly maps all preserved bonds.

  • ‘bondchange’ - (default) - use a smaller MIP formulation that implicitly maps all preserved bonds. This is typically the superior formulation.


A path to the cbc executable if it is not automatically detected by the system (e.g., it is not in the $PATH variable)


  • True - Uses the mapping in the reaction class (either given by the user, or from the heuristics) as an initial guess.

  • False (default) - Do not use the mappings as a starting guess.


  • True (default) - Attempt to remove redundancies (e.g. identical molecular structures in both reactants and products) to speed up the problem.

  • False - Do not attempt to simplify the problem.


  • True - Also solve the mappings for molecules that were filtered out by pre-processing (these maps should be obvious between identical molecular structures, but calculating them requires more computational effort)

  • False (default) - Ignore the mappings for filtered structures


The total time the MILP solver is allowed to run. Default is no time limit.

Table 2 Heuristics options




  • True (default) - Attempt to solve the problem using inexpensive heuristics rather than the MIP.

  • False - Directly solve the MIP.


  • True (default) - Calculate an extremely cheap but often loose lower bound based on the minimum number of required bond changes.

  • False - Do not calculate this lower bound.


  • True (default) - Calculate a cheap and relatively tight lower bound based on solving an assignment problem with local valence difference costs.

  • False - Do not calculate this lower bound.


  • True - Calculate an expensive lower bound using an iterative procedure.

  • False (default) - Do not calculate this lower bound.


  • True (default) - Calculate a cheap and often good upper bound using an assignment problem with costs based on local neighborhood difference between reactant and product atoms.

  • False - Do not calculate this upper bound.


  • True - Use an expensive, greedy algorithm to try to find an initial atom mapping.

  • False (default) - Do not calculate this upper bound.


  • True - Solve the quadratic assignment problem to local optimality to find an upper bound for the reaction mapping problem. This can be expensive but can often produce a tight upper bound.

  • False (default) - Do not calculate this upper bound.

Table 3 MIP Constraint Options




  • True (default) - Use valence constraints. These constraints involve limiting the possible number of mapped bonds based on the valences of mapped atoms (e.g., if we map a carbon with 2 oxygen neighbors to a carbon with only 1 oxygen neighbor, we know that at most one of the C-O bonds can be preserved.)

  • False - Do not use valence constraints.


  • True - Use tightbonds constraints. These constraints tighten the model by taking into account that a certain bond can only be mapped once. These constraints are typically expensive and usually do not improve performance.

  • False (default) - Do not use these constraints.


  • True - Take problem symmetries into account to reduce the number of redundant solutions. For example, in the CO2 molecule, the mappings involving the oxygens are interchangeable. These constraints typically do not improve performance.

  • False (default) - Do not use these constraints.


These options are only used if con_symmetry is True
  • 17 - Use a sparse symmetry-breaking constraint.

  • 18 - Use a medium-sparse symmetry-breaking constraint.

  • 19 (default) - Use a dense symmetry-breaking constraint.


These options are only used if con_symmetry is True
  • ‘cycle’ - consider cyclic symmetries

  • ‘node’ - consider nodal symmetries

  • ‘nodecycle’ (default) - consider both nodal and cyclic symmetries


These options are only used if con_symmetry is True
  • ‘reactant’ - use symmetries in the reactant molecule(s) to make constraints

  • ‘product’ - use the symmetries in the product molecule(s)

  • ‘reactantproduct’ (default) - use the symmetries in both reactants and products

Table 4 Output Options




  • True (default) - In solving a large problem set of reactions, write a one-line summary to stdout after each reaction map is solved.

  • False - Do not write anything to stdout.


We can set options in two ways. First by initializing the settings class, and by changing them directly. We can see the set options with the show_option attribute. Here one can see that the implictH and formulation options have been changed:

>>> import reactmap as rm
>>> settings = rm.Settings(implicitH = False)
>>> settings.formulation = 'bondmapping'
>>> settings.show_options()
                     RM Settings
Key                   Value            Default
print_level           status           status
log_level             info             info
print_progress        False            False
cbc_path              None             None
warmstart             False            False
preprocess            True             True
preprocess_map        False            False
use_heuristics        True             True
lb_bonds              False            False
lb_assignment         True             True
lb_branchtight        False            False
ub_assignment         True             True
ub_qap                False            False
ub_greedy             False            False
implicitH             False            True
con_valence           True             True
con_tightbonds        False            False
formulation           bondmapping      bondchange
con_symmetry          False            False
con_symmetry_version  cycle            cycle
con_symmetry_form     19               19
con_symmetry_side     reactantproduct  reactantproduct
write_log             False            False
time_limit            None             None



Resets all options to the default values.


This displays all settings options as well as their current and default values.