Rework the complex condition finder doc.

The result of the analysis is not gauranteed to include all segments in the true condition, only that the found condition is a superset of the true condition comprised only of segments from the true condition. This updates the doc to remove the claim that found conditions will contain all true condition segments. Additionally this reworks the 'Why this works' section to be a bit more rigorous.

Author: garretrieger

docs/experimental/closure_glyph_segmentation_complex_conditions.md

@@ -6,49 +6,49 @@ Date: Dec 17, 2025
 
 ## Introduction
 
-Before reading this document is recommended to first review the [closure glyph
-segmentation](./closure_glyph_segmentation.md) document.
+Before reading this document is recommended to first review the
+[closure glyph segmentation](./closure_glyph_segmentation.md) document. This document borrows concepts and terms from it.
 
 In closure glyph segmentation the closure analysis step is capable of locating glyph activation conditions that are
-either fully disjunctive or fully conjunctive (eg. A or B or C). It is not capable of finding conditions that are a mix
-of conjunction and disjunction (eg. (A and B) or (B and C)). These are referred to as complex conditions. By default
+either fully disjunctive or fully conjunctive (eg. `(A or B or C)`). It is not capable of finding conditions that are a mix
+of conjunction and disjunction (eg. `(A and B) or (B and C)`). These are referred to as complex conditions. By default
 glyphs with complex conditions are assigned to a patch that is always loaded, since the true conditions are not known.
 
-This document describes an algorithm which can be used to find the complete set of segments which are a part of the
-complex condition for a glyph. If the set of segments which are present in a condition is known, then we can form a
-purely disjunctive condition using those segments which is guaranteed to be a superset of the true condition. That is it
-will always activate at least when the true condition would. This property allows the superset condition to be used for
-a patch in place of the true condition without violating the closure requirement.
+This document describes an algorithm which can be used to find purely disjunctive conditions which are supersets of
+complex conditions. A superset condition is one that will activate at least whenever the true condition would. This
+property allows the superset condition to be used for a patch in place of the true condition without violating the
+closure requirement.
 
-For example if we had a glyph with a activation condition of ((A and B) or (B and C)) then this process will find the set
-of segments {A, B, C} which would form the superset condition (A or B or C). In a segmentation we could then have a
-patch with condition (A or B or C) which loads the glyph and this would satisfy the closure requirement. In the future
-if we decide to develop an analysis to find the true condition then the segment set found by this process could be used
-to narrow down the search space to only those segments involved in the condition.
+For a given complex condition there typically exists more than one possible superset disjunctive condition. The
+algorithm will find one of them, but not necessarily the smallest one. The found superset condition will always only
+contain only segments which appear in the original condition.
+
+For example if we had a glyph with a activation condition of `((A and B) or (B and C))` then this process will find one
+of the possible superset conditions such as `(A or C)`, `(A or B)`, `(B or C)`, or `(B)`. In a segmentation we could
+then have a patch with the found condition which loads the glyph and this would satisfy the closure requirement.
 
 ## Foundations
 
 The algorithm is based on the following assertions:
 
-1. For any complex activation condition of a glyph, a disjunction over all segments appearing in that condition
-   will always activate at least when the original condition does.
-   
-2. Given some fully disjunctive condition, we can verify that condition is sufficient to meet the glyph closure
-   requirement for a glyph by the following procedure: compute a glyph closure of the union of all segments except for
-   those in the condition. If the glyph does not appear in this closure, then the condition satisfies the closure
-   requirement for that glyph. This is called the “additional conditions” check.
+1. Given some fully disjunctive condition for a glyph, we can verify that the condition is a superset of the true
+   condition for the glyph and meets the closure requirement by the following procedure: compute a glyph closure of the
+   union of all segments except for those in the condition. If the glyph does not appear in this closure, then the
+   condition satisfies the closure requirement for that glyph and is a superset of the true condition. This is called
+   the “additional conditions” check.
 
-3. The glyph closure of all segments will include the glyphs that we are analyzing.
+2. The glyph closure of all segments includes the glyph that we are analyzing.
 
-4. We have a glyph which has some true activation condition. If we compute a glyph closure of some combination of
+3. We have a glyph which has some true activation condition. If we compute a glyph closure of some combination of
    segments, then adding or removing a segment, which is not part of the activation condition, to the glyph closure input
    will have no affect on whether or not the glyph appears in the closure output.
 
+4. The closure of no segments contains only glyphs from the initial font.
+
 ## The Algorithm
 
-For each glyph with a complex condition we can use the above to find the complete set of segments which are part of the
-glyph's complex condition. A condition which is a disjunction across these segments will satisfy the closure requirement
-for that glyph.
+For a glyph with a complex condition we can use the above to find a superset disjunctive condition for that
+glyph's complex condition. These conditions will satisfy the closure requirement for each glyph.
 
 ### Finding a Sub Condition
 
@@ -63,10 +63,10 @@ Inputs:
 Algorithm:
 
 1. Start with a set of all segments except those to be excluded, called `to_test`.
-2. Initialize a second set of segments, `required`, to the empty set.
-3. Remove a segment `s` from `to_test` and compute the glyph closure of `to_test U required`.
-4. If `glyph` is not found in the closure then add `s` to `required`.
-5. If `to_test` is empty, then return the  sub condition `required`.
+2. Initialize a second set of segments, `sub_condition`, to the empty set.
+3. Remove a segment `s` from `to_test` and compute the glyph closure of `to_test U sub_condition`.
+4. If `glyph` is not found in the closure then add `s` to `sub_condition`.
+5. If `to_test` is empty, then return the  sub condition `sub_condition`.
 6. Otherwise, go back to step 3.
 
 ### Finding the Complete Condition
@@ -83,32 +83,40 @@ Algorithm:
 2. Execute the `Finding a Sub Condition` algorithm with `condition` as the excluded set.
 3. Union the returned set into `condition`.
 4. Compute the glyph closure of all segments except those in `condition`.
-5. If `glyph` is found in the closure, then more conditions still exist. Go back to step 2.
+5. If `glyph` is found in the closure, then more sub conditions still exist. Go back to step 2.
 6. Return the complete condition, `condition`.
 
 ### Initial Font
 
-Any time a closure operation is executed by the above two algorithms it's necessary to union the subset definition 
-for the initial font into the closure input. That's because the closure of the initial font affects what's reachable
-by the segments.
+Any time a closure operation is executed by the above two algorithms it's necessary to union the subset definition for
+the initial font into the closure input. This is required because the closure of the initial font affects what's
+reachable by the segments.
 
 ### Why this works
 
+Here we show this procedure is guaranteed to find a disjunctive superset of a glyph's true condition which includes
+only segments from the true condition, when the glyph is not already in the initial font:
+
+* For each call to `Finding a Sub Condition` glyph will be in the closure of all non-excluded segments. For the first
+  call this is guaranteed by assertion (2). For subsequent calls this is guaranteed by the "additional conditions" check
+  which gates execution.
+
 * Any segments which are not part of the true condition will not impact the glyph's presence in the closure (assertion
-  (4)).  As a result they will never be moved into the `required` set and will not be returned by `Finding a Sub
-  Condition`.  Thus any segments returned by `Finding a Sub Condition` are part of the true condition.
+  (3)). Further by the previous point we know that at the start of `Finding a Sub Condition` the closure of all
+  non-excluded segments will contain glyph. Thus testing a segment which is not part of the true condition will never
+  result in glyph missing from the closure, and won't be added to `sub_condition`. Therefore `Finding a Sub Condition`
+  will only ever return segments that are part of the true condition.
 
-* Each iteration of `Finding a Sub Condition` is guaranteed to select at least one segment since we know that the
-  initial closure always starts with the glyph in it, and the closure of no segments will not have the glyph in it.  So
-  at some point during the algorithm the glyph must be found to not be present. In the first iteration this is a result
-  of assertion (3). For subsequent iterations this is guaranteed by the "additional conditions" check prior to starting
-  the iteration.
+* `Finding a Sub Condition` will always return at least one segment: if when the last segment is tested `sub_condition`
+  is still the empty set, then the closure will be on no segments and will not have glyph in it. This is a result of
+  assertion (4) and the premise that glyph is not already in the initial font. As a consequence the returned
+  `sub_condition` will always have at least one segment in it.
 
 * Since all returned segments from `Finding a Sub Condition` are excluded from future calls, there will be a finite
   number of `Finding a Sub Condition` executions which return only segments part of the true condition.
 
 * Lastly, the algorithm terminates only once the additional conditions check finds no additional conditions,
-  guaranteeing we have found the complete superset disjunctive condition.
+  guaranteeing we have found a superset disjunctive condition (assertion (1)).
 
 ## Making it More Performant
 

ift/encoder/complex_condition_finder.cc

@@ -27,8 +27,8 @@ struct Task {
   // analysis.
   SegmentSet excluded;
 
-  // These segments have been determined to be required.
-  SegmentSet required;
+  // These segments have been determined to be part of a sub condition.
+  SegmentSet sub_condition;
 
   // These segments have not yet been tested.
   SegmentSet to_be_tested;
@@ -76,7 +76,7 @@ struct Context {
     // covered by a task with no excluded segments.
     queue.push_back(Task{
         .excluded = {},
-        .required = {},
+        .sub_condition = {},
         .to_be_tested = all_segments,
         .glyphs = glyphs,
     });
@@ -126,7 +126,7 @@ struct Context {
 
     queue.push_back(Task{
         .excluded = condition,
-        .required = {},
+        .sub_condition = {},
         .to_be_tested = except,
         .glyphs = glyphs_with_additional_conditions,
     });
@@ -136,21 +136,21 @@ struct Context {
   }
 
   // Each analysis step checks one segment to see for which glyphs that segment
-  // is required. The supplied task data structure gives the specific state
+  // is relevant. The supplied task data structure gives the specific state
   // around which the segment is tested.
   //
   // To test a segment a closure is run without the segment being tested:
   // - For inscope glyphs which appear in the closure the test segment is not
-  //   required for these glyphs
+  //   relevant for these glyphs
   // - For inscope glyphs which do not appear in the closure the test segment is
-  //   required for these glyphs.
+  //   relevant for these glyphs.
   //
   // Based on the anlysis results up to two more analysis steps are spawned (one
-  // for glyphs where segment is required, the other where it is not required)
+  // for glyphs where segment is relevant, the other where it is not relevant)
   // to test the next segment.
   //
-  // Once all segments are tested the resulting minimal set of required segments
-  // is recorded in out. Lastly, the non-required segments are checked to see
+  // Once all segments are tested the resulting sub condition segments
+  // is recorded in out. Lastly, the non-relevant segments are checked to see
   // if additional conditions are present, if they are another analysis task is
   // queued to discover the additional conditions.
   Status RunAnalysisTask(
@@ -161,13 +161,13 @@ struct Context {
     }
 
     if (task.to_be_tested.empty()) {
-      return RecordMinimalCondition(task, glyph_to_conditions);
+      return RecordSubCondition(task, glyph_to_conditions);
     }
 
     segment_index_t test_segment = *task.to_be_tested.min();
     task.to_be_tested.erase(test_segment);
 
-    SegmentSet closure_segments = task.required;
+    SegmentSet closure_segments = task.sub_condition;
     closure_segments.union_set(task.to_be_tested);
     GlyphSet closure_glyphs = TRY(SegmentClosure(closure_segments));
 
@@ -178,42 +178,42 @@ struct Context {
 
     queue.push_back(Task{
         .excluded = task.excluded,
-        .required = task.required,
+        .sub_condition = task.sub_condition,
         .to_be_tested = task.to_be_tested,
         .glyphs = doesnt_need_test_segment,
     });
 
-    task.required.insert(test_segment);
+    task.sub_condition.insert(test_segment);
     queue.push_back(Task{
         .excluded = task.excluded,
-        .required = task.required,
+        .sub_condition = task.sub_condition,
         .to_be_tested = task.to_be_tested,
         .glyphs = needs_test_segment,
     });
 
     return absl::OkStatus();
   }
 
-  // A minimal condition has been found, record it and kick off any
+  // A sub condition has been found, record it and kick off any
   // further analysis needed for additional conditions.
-  Status RecordMinimalCondition(
+  Status RecordSubCondition(
       Task task, btree_map<glyph_id_t, SegmentSet>& glyph_to_conditions) {
     for (glyph_id_t gid : task.glyphs) {
-      glyph_to_conditions[gid].union_set(task.required);
+      glyph_to_conditions[gid].union_set(task.sub_condition);
     }
 
-    // We have identified a minimal set of required segments for glyphs,
-    // however as usual there may be remaining additional conditions which we
-    // need to check for
-    task.excluded.union_set(task.required);
+    // We have identified a sub condition for glyphs, however as usual
+    // there may be remaining additional conditions which we need to
+    // check for
+    task.excluded.union_set(task.sub_condition);
     auto [additional_condition_glyphs, remaining] =
         TRY(HasAdditionalConditions(task.excluded, task.glyphs));
 
     // Anything left in glyphs has additional conditions, recurse again to
     // analyze them further
     queue.push_back(Task{
         .excluded = task.excluded,
-        .required = {},
+        .sub_condition = {},
         .to_be_tested = remaining,
         .glyphs = additional_condition_glyphs,
     });
@@ -264,7 +264,7 @@ static SegmentSet NonEmptySegments(
   return segments;
 }
 
-StatusOr<btree_map<SegmentSet, GlyphSet>> FindMinimalDisjunctiveConditionsFor(
+StatusOr<btree_map<SegmentSet, GlyphSet>> FindSupersetDisjunctiveConditionsFor(
     const RequestedSegmentationInformation& segmentation_info,
     const GlyphConditionSet& glyph_condition_set,
     GlyphClosureCache& closure_cache, GlyphSet glyphs) {
@@ -275,7 +275,7 @@ StatusOr<btree_map<SegmentSet, GlyphSet>> FindMinimalDisjunctiveConditionsFor(
   // may interact with the GSUB table. Any segments which don't interact with
   // GSUB will already have relavent conditions discovered via the standard
   // closure analysis. Only segments which interact with GSUB may be part of
-  // complex conditions (since complex conditions required at least one 'AND'
+  // complex conditions (since complex conditions require at least one 'AND'
   // which only GSUB can introduce). As a result we can exclude any segments
   // with no GSUB interaction from this analysis which should significantly
   // speed things up.

ift/encoder/complex_condition_finder.h

@@ -9,21 +9,21 @@
 
 namespace ift::encoder {
 
-// Finds the minimal purely disjunctive conditions that activate each
+// Finds superset purely disjunctive conditions that activate each
 // provided glyph. Returns a map from each condition to the activated
 // glyphs.
 //
 // Takes a glyph condition set which will be used as a starting point.
 //
-// A minimal purely disjunctive condition is the complete set of segments
-// which appear in the true activation condition for a glyph. The
-// purely disjunctive version is a super set of the true condition and
-// will activate at least whenever the true condition would.
+// A superset purely disjunctive condition  will activate at least
+// whenever the true condition would. It will only ever include segments
+// that appear in the true condition. There are typically multiple
+// possible superset conditions. This will find one of them.
 //
 // For example if a glyph has the true condition (a and b) or (b and c)
-// this will find the condition (a or b or c).
+// this could find the condition (a or c).
 absl::StatusOr<absl::btree_map<common::SegmentSet, common::GlyphSet>>
-FindMinimalDisjunctiveConditionsFor(
+FindSupersetDisjunctiveConditionsFor(
     const RequestedSegmentationInformation& segmentation_info,
     const GlyphConditionSet& glyph_condition_set,
     GlyphClosureCache& closure_cache, common::GlyphSet glyphs);