The internals of the Matlab Toolbox for Transmission Channel Analysis all resolve around the type Q, which is the internal representation of a transmission condition using the variables of the systems form; thus \(x_i\) and not\(y_{i,t}\).
Q
Q Represents a transmission condition.
The Q class is used to define transmission conditions based on Boolean statements. A transmission condition is denoted as \(Q(b)\), where \(b\) is a Boolean statement involving variables x<num>, such as x1, x2, etc. Boolean statements should only contain AND (&) and NOT (!) operations.
Properties
vars (cell array of strings): Contains the Boolean variable expressions.
multiplier (vector of numbers): Multipliers associated with each term.
Methods
Q: Constructor to create a transmission condition.
The recommended constructor is Q(i), where i is an integer representing a variable index.
Other constructors are for internal use and may lead to incorrect results if misused.
DO NOT use OR (|) inside the string input for Q, as it is not supported.
The basic idea is to start with a singleton statement, such as \(x_i\), \(\neg x_i\) or sometimes even just \(\text{TRUE}\). Each of these singleton – or atomic – statements refers to the simplest transmission channel in which \(x_i\) must be on the path, \(x_i\) cannot be on the path, or in which case the condition is always true. Such singleton statement can be created in the following way.
% x1 must be on the pathx1=Q(1);% x1 cannot be on the pathnotX2=Q('!x2');% TRUET=Q('T');
More complex transmission conditions are then simply a combination of these singleton statements. More precisely, a transmission condition q1 can be combined with another transmission condition q2 using any of AND (&), OR (|) and NOT (~)1. Throughout, parentheses can be used to change the precedence. In the following we will describe how such combinations are internally implemented.
Combining two conditions using AND (&)
Suppose we wanted to combine two conditions q1::Q and q2::Q using an AND. Thus, suppose we wanted to do
q1&q2
This is achieved by extending and for the type Q. However, key in the internal implementation is the following assumption.
Note 1: Assumption 1
The transmission condition q consists of only conjunctions (&) and negations (!).
Under Assumption 1q1 and q2 both consist of only conjunctions and disjunctions. This immediately implies that their conjunction will also only consist of conjunctions and negations. We can thus simply “concatenate” the two conditions. This is basically what we internally do, with the caveat that the conditions are represented using String and that, for algorithimic purposes, we prefer the variables to be ordered in the statement.
The detailed internal implementation is given by
Q.and
& combine two transmission conditions using logical AND.
result = q1 & q2 performs a logical AND operation between two transmission conditions, returning a new Q object. This is the same as \(Q(b \land b')\) where \(b\) and \(b'\) are the Boolean conditions for q1 and q2 respectively.
Arguments
obj1 (Q): First transmission condition.
obj2(Q): Second transmission condition.
Returns
result(Q): The combined transmission condition.
Example:
q1=Q(1);q2=Q(2);q=q1&q2;% Returns Q("x2 & x1")
See also or (|), not (~)
While concatenating the two conditions, we need to watch out that no contradictions are being introduced. Contradictions are any statements along the lines \(x_i \land \neg x_i\) which would always result in false. This is taken care of by the following functions.
checkContradiction
checkContradiction Check for contradictions of the form x1 & ~x1 (x1 & !x1).
[hasContradiction, contradictions] = checkContradiction(varAnd, varNot) checks whether there is a contradiction where a variable appears in both varAnd and varNot, meaning it is simultaneously required and forbidden.
Arguments
varAnd (vector or cell array of vectors): AND variable numbers obtained from getVarNumsAndMultiplier.
varNot (vector or cell array of vectors): NOT variable numbers obtained from getVarNumsAndMultiplier.
Returns
hasContradiction (logical): True if any contradictions exist.
contradictions (vector of logicals): A vector indicating which elements yield a contradiction.
Notes
This function is used in removeContradictions to eliminate contradicting terms, which helps speed up the simplification process by reducing the total number of terms.
See also removeContradictions, getVarNumsAndMultiplier
removeContradictions
removeContradictions Remove contradicting terms from a transmission condition.
q = removeContradictions(q) removes terms that contain contradictions of the form x_i & !x_i, which always evaluate to false and contribute zero to the transmission effect. Behaviour of the function can be changed by setting REMOVECONTRADICTIONS=false locally.
Arguments: - q (Q): A transmission condition. See also Q and makeCondition.
Returns: - If REMOVECONTRADICTIONS is set to false, the input q is returned unchanged. - If REMOVECONTRADICTIONS is true or not set: 1. If all terms are contradicting, Q("T", 0) is returned, which represents a transmission effect of zero. 2. If some terms are non-contradicting, only the non-contradicting terms are retained in the output.
Example
setRemoveContradictions(true);% on by defaultq=Q('x1',1);q=removeContradictions(q);% Returns q unchanged (no contradictions).q=Q('x1 & !x1',1);q=removeContradictions(q);% Returns Q('T', 0).q=Q({'x1 & !x1','x1 & x2'}, [1,1]);q=removeContradictions(q);% Returns Q('x2 & x1', 1).setRemoveContradictions(false);q=Q('x1 & !x1',1);q=removeContradictions(q);% Returns the original q.
Notes
If REMOVECONTRADICTIONS is not explicitly set, contradictions are removed by default.
As stated in the overview of the documentation, removal of contradictions is governed by the global REMOVECONTRADICTION and the utility function setRemoveContradictions. Not removing contradictions does not lead to mistakes in the computation, but can result in longer computations. Contrary, removing contradictions can lead to longer compile times – it takes longer to compile the transmission conditions. Thus, a trade-off between compile and computing time exists.
setRemoveContradictions
setRemoveContradictions Set the global flag for removing contradictions in transmission conditions.
setRemoveContradictions(bool) controls whether contradictions in transmission conditions are removed when calling setRemoveContradictions.
Arguments
bool (logical): If true, contradictions of the form “x_i & !x_i” will be removed from transmission conditions. If false, contradictions will not be removed.
Let q1 and q2 be again two transmission conditions. Suppose their internal Boolean conditions are given by \(b\) and \(b'\) respectively, with both satisfying Assumption 1. The rules for manipulating transmission conditions then imply \[
Q(b \lor b') = Q(b) + Q(b') - Q(b \land b').
\] Implementation of OR (|) therefore simply uses AND and the ability for Q to represent multiple terms with different multipliers. The precise implementation of OR can be found in the following function.
Q.or
| Combine two transmission conditions using a logical OR.
result = q1 | q2 performs a logical OR operation between two transmission conditions, returning a new Q object.
Arguments
obj1 (Q): First transmission condition.
obj2 (Q): Second transmission condition.
Returns
result (Q): The combined transmission condition.
Example
q1=Q(1);q2=Q(2);q=q1|q2;
See also and (&), not (~)
Negating a condition using NOT (~)
Suppose a transmission condition is given by q which internally represents the Boolean condition \(b\). By the rules for manipulating transmission conditions we then know that \[
Q(\neg b) = Q(T) - Q(b),
\] where \(T\) represents the Boolean condition that is always true. This can easily be represented using Q through its ability to represent multiple terms and multipliers. Specifically, we simply replace the original transmission condition with a new one that consists of one additional term, representing true, and switch the sign of all original terms of the condition. The following function implements this behaviour.
Q.not
~ Negate a boolean condition using the logican NOT.
result = ~q negates a transmission condition, creating a condition where the given Boolean statement does not hold.
Arguments
obj (Q): A transmission condition to negate.
Returns
result (Q): The negated transmission condition.
Example
q1=Q(1);q=~q1;
Notes
If the condition consists of a single variable, it is simply negated.
If the condition is more complex, an auxiliary "T" (true) condition is used and the returned condition is equivalent to \(Q(T) - Q(b)\) where \(b\) is the origional Boolean condition.
See also and (&), or (|)
Parsing transmission conditions using makeCondition
Rather than letting the user create all variables manually via x1=Q(1) etc., we provide the function makeCondition. This function simply matches all variables in a string with the regex x\d+, creates the variables using the above way, and then evaluates the entire condition to create the final condition. Due to the operator overloading above, the final result will be a valid and correct transmission condtion. However, key to this correctness is that all variables match the provided regex pattern. Thus, all variables must be of the form x1, x2, etc.
For user friendliness, we also provide a version of makeConditionY that takes variables of the dynamic form, i.e. \(y_{i,t}\). However, all that this function does is to translate all variables into variables of the systems form and then calls the method explained above.
In any case, makeCondition and makeConditionY should be seen as utility functions with the main funcionality being dependent on correct implementation of Q, &, |, and ~ as explained above.
makeCondition
makeCondition Create a transmission condition from a Boolean string.
q = makeCondition(s) constructs a transmission condition \(Q(b)\) from a Boolean statement given as a string. The Boolean expression should use variables of the systems form x<num>, where <num> represents a variable index.
Arguments
s (string): A Boolean condition string where variables must be represented using x<num>.
Returns
q (Q): A transmission condition.
Example
s="x2 & !x3";cond=makeCondition(s);
Notes
Boolean conditions can include AND (&), NOT (! or ~), OR (|), and parentheses.
The resulting transmission condition can be used in transmission to calculate the transmission effect.
See also transmission, makeConditionY
makeConditionY
makeConditionY Create a transmission condition from a Boolean string using dyanmic form variables.
q = makeConditionY(strY, order) constructs a transmission condition \(Q(b)\) from a Boolean statement specified in terms of dynamic system variables (i.e., y_{i,t} notation).
Arguments
strY (string): A Boolean condition string where variables are represented as y_{i,t}, with i as the variable index and t >= 0 as the time period. t=0 corresponds to the contemporaneous horizon.
order (vector of integers): The variable ordering defined by the transmission matrix.