Note: The listed changes reference equations and sections from the article
-
Fix a critical bug for the previous change: the randomized permutation of controls an concentratios often produced repeated results.
-
Moved model parameters up, so the user has easier time accessign them. Added proper explanations and two new flags:
- randomize_order_of_material_concentrations to enable the shuffling of controls and concentrations during quadrant distribution (making the change in 1.3.3 optional)
- flag_consolidate_controls if the user wants all controls to be placed within the same criteria set or not. If disabled, each control type is optimized separately from each other, making possible placing, e.g., positive and negative controls as neighbours to each other
-
Set the number of fake edge wells to 0, as of now (a tunable parameter, visible to the user). The reasoning is that fake edge wells are likely useful for sparse layout optimization (thus, the user can set it to 4 or 6). If the layout is dense, some materials will likely be pushed to edges anyway.
- Updated symmetry-breaking lexicographical constraints (when optional constraints are disabled or not applied). Instead of enforcing the order which goes from replicates of first concentration, to replicates of second concentration, to third, etc, the lexigographical order now mixes the order of the replicates, i.e., instead of lex_greater_chain([Coordinates_j | j=1..n]) it is lex_greater_chain([Coordinates_j | j=randomized_order_of_wells]). This should remove the situation when a specific concentration would have a tendency to gravitate towards certain rows. The new allocation is much more equitable. NOTE: if the criteria set is under the optional constraints, then this change does not affect the constraint, since the lex_chain_greater is applied on individual concentrations.
- In the same spirit, when we list concentrations in the vector emptywells_controls_compounds_names_concentrations, the previous versions listed them in a given manner (as they listed in the data file). In 1.3.3, we shuffle the list of concentrations to randomize their assignments within quadrants. It is useful in situations when the number of replicates for each material-concentration is divisible by 4: in that situation, all concentrations of the same dose would be in the same quadrant, which is not desirable. It is a very specific edge case, but it needs to be accounted for. The resulting list would look like this: [dr1-ct2, dr1-ct1, dr1-ct3, dr2-ct3, dr2-ct2, dr2-ct1, dr3-ct1, dr3-ct3, ...] Note: This order must be matched in the declaration of array emptywells_controls_compounds_qtys_total (if a change is introduced, where the number of replicates between concentrations differs.
These changes do not affect performance, but they will result in more robust microplate layouts.
- Updated constraints related to min_distance and min_distance_ctrs. i.e, instead of, e.g., min_distance = min(criteria_set_min_distances), using criteria_set_min_distance >= min_distance. It should propagate better and be consistent with the change in constraints introduced in 1.3.0
- A more detailed error message when a heuristic used for the replicates_on_same_plate strategy produces unfeasible material allocations, to help the user work around it
- lex_chain_greater symmetry-breaking constraints are not posted when the criteria-set or a material-concentration has <2 wells (a slight optimization during compilation and, possibly, reduces posting of unnecessary constraints)
- updated the constraint model. I replaced the constraints in equation (15) of the original article with. Instead of using criteria-set-minimal-distance-variable = min(the-list-of-distances-in-the-criteria-set), COMPD now uses a set of constraints, criteria-set-minimal-distance-variable =< distance-in-the-criteria-set for each distance. It reduces the memory consumption by ~5-10% and, in some cases and some solvers, slightly reduces the solution time
- Added a detailed comment behind the quadrant distribution process (COMPD uses deterministic round-robin allocation followed by sequential bin packing). No changes in the behaviour of the model (it remained the same from 1.0), it is added for posterity and clarity
- refactoring: applying the same approach of helper functions introduced in 1.2.8 to the domain and all optional constraints. Benefits - readability and encapsulated logic. Significantly reduced number of lines
- minor refactoring: introduced three helper functions to encapsulate common logic for calculating arrays emptywells_controls_compounds_concentrations_on_different_* (reduction by ~60 lines)
- further minor refactoring to slightly reduce the number of lines (not that much) and make the code slightly more readable (removing well_included_by_optional_constraints since it's possible to simply use negation of well_excluded_by_optional_constraints)
- fixed an old bug that was present since 1.0: constraint that iterated over materials and used well_excluded_by_optional_constraints (or its equivalent in 1.0), was incorrectly passing a criteria set index instead of a material index. In most cases, it did not produce a serious violation of optional constraints, but it was still an error in logic that the model was supposed to obey.
- further minor refactoring to slightly reduce the number of lines (not that much) and make the code slightly more readable (introducing functions well_excluded_by_optional_constraints and well_included_by_optional_constraints)
- fixed a cosmetic bug introduced in 1.2.5 when some debugging information was printed despite the debugging flag being false
- further minor refactoring to slightly reduce the number of lines (not that much) and make the code slightly more readable
- minor refactoring: rewrote some of the conditions for the optional constraints to be more concise and direct, without changing their structure or behavior
- Added a couple of commentaries
Minor fixes (to handle rare edge cases):
min_dist_edgesis now guaranteed to be a positive integer (otherwise it conflicted with domains of distance variables)- generalized the previous fix, where instead of checking the number of rows/columns, it takes an already existing flag
use_quadrant_distribution(for simplicity)
Minor fixes (to handle rare edge cases):
- fixing an upper limit for GCC optional constraint when applied on multiple plates (otherwise it can be too restrictive)
- if the number of rows/columns is equal to 1, then set the respective flags for optional constraints to
false(to not put unnecessary constraints in this situation) - A few lines of text are aligned in a more consistent manner
Minor fixes:
- added a warning when the number of wells per line is =< 0 (otherwise the model stopped without explanation)
- a couple of counting tensors were renamed (removed
min_distfrom their names, as these tensors are not used during the calculation of the minimal distances)
Optional constraints reworked to be more nuanced/consistent:
- if a half (top/bottom/right/left) has fewer or an equal number of wells than its number of rows/columns, then all_different is applied (same as before),
- if a half (top/bottom/right/left) has a greater number of wells than its number of rows/columns, then the global cardinality constraint (gcc) is applied to ensure that there is at least one well per row/column in this half.
Thus, we'll first split existing flags emptywells_controls_compounds_concentrations_on_different_* (which correspond) into:
- emptywells_controls_compounds_concentrations_on_different_rows_top (top, all_different)
- emptywells_controls_compounds_concentrations_on_different_rows_top_gcc (top, gcc)
- emptywells_controls_compounds_concentrations_on_different_rows_btm (bottom, all_different)
- emptywells_controls_compounds_concentrations_on_different_rows_btm_gcc (bottom, gcc)
- emptywells_controls_compounds_concentrations_on_different_columns_lft (left, all_different)
- emptywells_controls_compounds_concentrations_on_different_columns_lft_gcc (left, gcc)
- emptywells_controls_compounds_concentrations_on_different_columns_rgt (right, all_different)
- emptywells_controls_compounds_concentrations_on_different_columns_rgt_gcc (right, gcc)
Same with flags emptywells_controls_compounds_concentrations_on_different_*_all_plates
This behaviour should:
- reduce the number of situations when the model is unsatisfiable due to optional constraints
- ensure that every row/column is covered if there are too many wells with the criteria set (previously, it was not enforced)
- the previous point, potentially, can lead to increased performance as the number of potential well placements is reduced (this point must be tested)
These changes replace Equations 7-11 with a more sophisticated set of constraints. They also slightly update Equations 12 and 13
Note: the resulting behaviour still depends on the placement of wells between the quadrants. Thus, if the division of wells is unbalanced, then some rows/columns in one half could be empty, while the other half would have 2+ wells per row/column.
- Now, the flag
inner_empty_edgeis not hard-coded, and instead depends on the optional input parameterinner_empty_edge_input. i.e. the data file now determines what kind of borders the model must use.
-
Changes in the handling of fake edge wells:
- the threshold on the maximum number of wells within a criteria set to activate the fake edge wells for the criteria set is increased from 4 to 6 (see end of Section 4.2);
- the number of fake edge wells is increased from 8 to 16 (f = 16, see Section 4.5);
- coordinates of fake edge wells are also adjusted, by moving them one row/column away from the plate line (updates Equation 14)
-
Adjusted the optimization criteria to give more weight to the minimal distances within criteria sets that contain controls. i.e. it should result in the optimization process that priotitizes the placement of controls first. COMPD's main strength, according to the evaluation, is the placement of control wells given enough time. Thus, it would be prudent to capitalize on this strength and ensure that even if the optimization process is interrupted early, we still get a layout with satisfactory placement controls.
Initial version. Corresponds to the article (tbd)