Description

Programs created using our internal tools sometimes include routines whose resources should only be counted once, a.k.a. as first-pass only routines. However, those are not easily representable in QREF, and, therefore, cannot be correctly processed in Bartiq, leading to vast overcounts of resources. This PR deals with this issues. To this end I introduced the following changes:

1. Modified both Routine and CompiledRoutine to capture necessary information for processing first-pass resources.
2. Modified compilation engine to take those informations into account (obviously, this includes evaluation)
3. Added support for the above changes in QREF - Bartiq integration.

The details of how everything works are below.

High-level overview

To tackle the problem, we allow marking some uncompiled routines as being first-pass only. When a routine is marked in this way, it tells the compilation engine that if this particular routine is repeated, then it should only contribute to the resources once. For instance, consider routine A, with children B and C, with an additive resource x. Suppose that B is marked as first-pass only, C is not marked as first-pass only, and A is repeated 10 times (using constant repetition). Then A.x would be equal to 10 * C.x + A.x (as oppose to 10 * C.x + !0 * A.x).

However, this is not enough, as one has to take into account the whole hierarchy of the program. For instance, if A has child B with child C that has a first-pass child D, and A is repeated 10 times, we have to somehow know that part of resources in C are actually coming from a first-pass child. Note that this is only necessary for compiled routines. To this end, we also store "first-pass resources" in any given routine that requires it. Those resources propagate during compilation, and are also correctly combined in case there are sourced from multiple subroutines.

Changes to Routine and CompiledRoutine

• Addition of first_pass_only flag to both routine types.
• Addition of first_pass_resources field to Compiledroutine

Changes to compilation engine

The largest part of the compilation engine remain unchanged, except the following:

• In case of repetitions (which we implement as a wrapper around a single child) the repeated resources are computed in for child's resources diminished by the value of corresponding first pass resource. The diminishing happens either by subtraction, or by multiplication (depending on type of resource). Then, the computed value is multiplied by/added to the corresponding first-pass value. For instance, suppose child C is repeated 10 times. Let value if its additive x resource be 5, and corresponding first pass value be 2. Then, instead of computing the total value of x as 10 * 5, we compute it as 10 * (5 - 2) + 2.
• The first-pass resources for any given routine are determined as follows:
  • If the routine is first-pass only, all its resources are first-pass resources (obviously)
  • If the routine is not first-pass only, then its first pass resources are sums/products of first-pass resources of its children.
• (relevant only if resources are not being expanded) The resources can now be expressed in terms of children's first pass resources, using child_name.__fp__resource_name` placeholder. Those variables are added to the parameter map during the compilation (it it is required) and during evaluation (always).

Boy-scout changes

• Introduced a helper function for collecting variables for evaluation from routine's children.
• Fixed aggregation tests, because they were actually using the wrong type of routine.

Please verify that you have completed the following steps

• I have self-reviewed my code.
• I have included test cases validating introduced feature/fix.
• I have updated documentation.