--- title: Classical Expressions (latest version) description: API reference for Classical Expressions in the latest version of qiskit-c source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit-c/qk-classical-expressions --- # Classical Expressions The Qiskit C API for classical expressions provides facilities for inspecting classical expressions used in Qiskit. This API enables users to traverse and examine expression trees through a set of enums, structs, and accessor functions. You can inspect the structure of expressions, identify node types, query type information and access detailed properties of each node in the expression tree. Currently, classical expressions can only be accessed through the control-flow API, for example when querying conditions that are comprised of classical expressions. Note that the functions in this API return borrowed pointers that remain valid as long as the parent expression tree exists, so these pointers do not need to be freed. ## Data Types ### QkExprNodeKind `enum QkExprNodeKind` The different types of expression nodes that can appear in a classical expression tree. *Values:* #### enumerator QkExprNodeKind\_Unary Unary operation expression (e.g., NOT, negation) #### enumerator QkExprNodeKind\_Binary Binary operation expression (e.g., AND, OR, arithmetic operations) #### enumerator QkExprNodeKind\_Cast Type cast expression #### enumerator QkExprNodeKind\_Value Literal value expression #### enumerator QkExprNodeKind\_Var Variable reference expression #### enumerator QkExprNodeKind\_Stretch Stretch expression (timing-related) #### enumerator QkExprNodeKind\_Index Index/subscript expression ### QkExprType `enum QkExprType` The data types that can be used in classical expressions. *Values:* #### enumerator QkExprType\_Bool Boolean type #### enumerator QkExprType\_Duration Duration type #### enumerator QkExprType\_Float Floating-point type #### enumerator QkExprType\_Uint Unsigned integer type ### QkExprTypeInfo `struct QkExprTypeInfo` The complete representation of the data type used for an expression. #### QkExprType ty The expression type #### uint32\_t width Bit width for the Uint expression type ### QkUnaryOpType `enum QkUnaryOpType` The operation types a unary expression can hold. Values are one-based to match the Python convention of the classical expression system. *Values:* #### enumerator QkUnaryOpType\_BitNot Bitwise NOT operation #### enumerator QkUnaryOpType\_LogicNot Logical NOT operation #### enumerator QkUnaryOpType\_Negate Arithmetic negation ### QkUnaryExprInfo `struct QkUnaryExprInfo` Describes a unary expression, including its operator, operand, result type and whether it is constant. Returned by the `qk_expr_unary_info` function. The `operand` field is a borrowed pointer to the operand of the unary operation expression. #### QkUnaryOpType op The unary operator #### const QkExprNode \*operand Borrowed pointer to the operand expression #### QkExprTypeInfo ty Result type of the operation #### bool constant Whether the expression is constant ### QkBinaryOpType `enum QkBinaryOpType` The operation types a binary expression can hold. Values are one-based to match Python convention. *Values:* #### enumerator QkBinaryOpType\_BitAnd Bitwise AND operation #### enumerator QkBinaryOpType\_BitOr Bitwise OR operation #### enumerator QkBinaryOpType\_BitXor Bitwise XOR operation #### enumerator QkBinaryOpType\_LogicAnd Logical AND operation #### enumerator QkBinaryOpType\_LogicOr Logical OR operation #### enumerator QkBinaryOpType\_Equal Equality comparison #### enumerator QkBinaryOpType\_NotEqual Inequality comparison #### enumerator QkBinaryOpType\_Less Less than comparison #### enumerator QkBinaryOpType\_LessEqual Less than or equal comparison #### enumerator QkBinaryOpType\_Greater Greater than comparison #### enumerator QkBinaryOpType\_GreaterEqual Greater than or equal comparison #### enumerator QkBinaryOpType\_ShiftLeft Left shift operation #### enumerator QkBinaryOpType\_ShiftRight Right shift operation #### enumerator QkBinaryOpType\_Add Addition operation #### enumerator QkBinaryOpType\_Sub Subtraction operation #### enumerator QkBinaryOpType\_Mul Multiplication operation #### enumerator QkBinaryOpType\_Div Division operation ### QkBinaryExprInfo `struct QkBinaryExprInfo` Describes a binary expression, including its operator, operands, result type and whether it is constant. Returned by the `qk_expr_binary_info` function. The `left` and `right` fields are borrowed pointers to the operands of the binary operation expression. #### QkBinaryOpType op The binary operator #### const QkExprNode \*left Borrowed pointer to the left operand expression #### const QkExprNode \*right Borrowed pointer to the right operand expression #### QkExprTypeInfo ty Result type of the operation #### bool constant Whether the expression is constant ### QkCastExprInfo `struct QkCastExprInfo` Describes a cast expression, including the operand, target type, whether it is implicit, and whether it is constant. Returned by the `qk_expr_cast_info` function. The `operand` field is a borrowed pointer to the operand of the cast expression. #### const QkExprNode \*operand Borrowed pointer to the operand expression being cast #### QkExprTypeInfo ty Target type of the cast #### bool implicit Whether the cast is implicit (automatic) or explicit #### bool constant Whether the expression is constant ### QkIndexExprInfo `struct QkIndexExprInfo` Describes an index expression, including the target, index, result type and whether it is constant. Returned by the `qk_expr_index_info` function. The `target` and `index` fields are borrowed pointers to the target and index of the index operation expression. #### const QkExprNode \*target Borrowed pointer to the target expression being indexed #### const QkExprNode \*index Borrowed pointer to the index expression #### QkExprTypeInfo ty Result type of the indexing operation #### bool constant Whether the expression is constant ### QkDurationType `enum QkDurationType` Represents different time units used in duration expressions. *Values:* #### enumerator QkDurationType\_Dt System time units #### enumerator QkDurationType\_Ps Picoseconds #### enumerator QkDurationType\_Ns Nanoseconds #### enumerator QkDurationType\_Us Microseconds #### enumerator QkDurationType\_Ms Milliseconds #### enumerator QkDurationType\_S Seconds **union QkDurationValue** *#include \* A union to hold either system time units (dt) as an integer or real time as a float. This union is part of the `QkDurationInfo` struct and should not be used directly. ### int64\_t dt System time units (active when `ty` in `QkDurationInfo` is `QkDurationType_Dt`) ### double time Real time value (active for all other duration types) ### QkDurationInfo `struct QkDurationInfo` The complete representation of a duration value. The `ty` field acts as a discriminant that determines which field of the `value` union is active. When initialized from C, it is the user’s responsibility to ensure that: - When `ty` is `QkDurationType_Dt`, the duration is stored as an integer in `value.dt`. - For all other duration types the duration is stored as a floating-point value in `value.time`. #### QkDurationType ty The duration unit type (discriminant for the union) #### QkDurationValue value The duration value ## Functions ### qk\_expr\_kind `QkExprNodeKind qk_expr_kind(const QkExprNode *expr)` Return the kind of a classical expression node. #### Example ```c QKExprNodeKind kind = qk_expr_kind(expr); ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to the expression node to inspect. **Returns** The kind enum describing which concrete expression variant `expr` contains. ### qk\_expr\_binary\_info `QkBinaryExprInfo qk_expr_binary_info(const QkExprNode *expr)` Extract information from a binary expression node. Panics if `expr` does not point to a binary expression node. #### Example ```c QkBinaryExprInfo info = qk_expr_binary_info(expr); const QkExprNode *lhs = info.left; const QkExprNode *rhs = info.right; ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to a binary expression node. **Returns** A `QkBinaryExprInfo` struct describing the operator, operands, result type, and whether the expression is constant. ### qk\_expr\_unary\_info `QkUnaryExprInfo qk_expr_unary_info(const QkExprNode *expr)` Extract information from a unary expression node. Panics if `expr` does not point to a unary expression node. #### Example ```c QkUnaryExprInfo info = qk_expr_unary_info(expr); QkUnaryOpType op = info.op; ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to a unary expression node. **Returns** A `QkUnaryExprInfo` struct describing the operator, operand, result type, and whether the expression is constant. ### qk\_expr\_cast\_info `QkCastExprInfo qk_expr_cast_info(const QkExprNode *expr)` Extract information from a cast expression node. Panics if `expr` does not point to a cast expression node. #### Example ```c QkCastExprInfo info = qk_expr_cast_info(expr); const QkExprNode *operand = info.operand; ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to a cast expression node. **Returns** A `QkCastExprInfo` struct describing the operand, destination type, whether the cast is implicit, and whether the expression is constant. ### qk\_expr\_index\_info `QkIndexExprInfo qk_expr_index_info(const QkExprNode *expr)` Extract information from an index expression node. Panics if `expr` does not point to an index expression node. #### Example ```c QkIndexExprInfo info = qk_expr_index_info(expr); const QkExprNode *target = info.target; const QkExprNode *index = info.index; ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to an index expression node. **Returns** A `QkIndexExprInfo` struct describing the indexed target, index expression, result type, and whether the expression is constant. ### qk\_expr\_as\_value `const QkValue *qk_expr_as_value(const QkExprNode *expr)` Return a view into the underlying value of the expression node. Panics if `expr` does not point to a value expression node. #### Example ```c const QkValue *value = qk_expr_as_value(expr); ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to a value expression node. **Returns** A pointer to the `QkValue` stored inside `expr`. ### qk\_expr\_as\_var `const QkVar *qk_expr_as_var(const QkExprNode *expr)` Return a view into the underlying variable of the expression node. Panics if `expr` does not point to a variable expression node. #### Example ```c const QkVar *var = qk_expr_as_var(expr); ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to a variable expression node. **Returns** A pointer to the `QkVar` stored inside `expr`. ### qk\_expr\_as\_stretch `const QkStretch *qk_expr_as_stretch(const QkExprNode *expr)` Return a view into the underlying stretch of the expression node. Panics if `expr` does not point to a stretch expression node. #### Example ```c const QkStretch *stretch = qk_expr_as_stretch(expr); ``` #### Safety Behavior is undefined if `expr` is not a valid, non-null pointer to a `QkExprNode`. **Parameters** - **expr** – A pointer to a stretch expression node. **Returns** A pointer to the `QkStretch` stored inside `expr`. ### qk\_value\_type\_info `QkExprTypeInfo qk_value_type_info(const QkValue *value)` Return the type information of a value. #### Example ```c QkExprTypeInfo type_info = qk_value_type_info(value); ``` #### Safety Behavior is undefined if `value` is not a valid, non-null pointer to a `Value`. **Parameters** - **value** – A pointer to the `QkValue` to inspect. **Returns** A `QkExprTypeInfo` struct containing the value type information. ### qk\_value\_duration\_info `QkDurationInfo qk_value_duration_info(const QkValue *value)` Extract structured information from a duration value. Panics if `value` does not point to a duration value. #### Example ```c QkDurationInfo info = qk_value_duration_info(value); ``` #### Safety Behavior is undefined if `value` is not a valid, non-null pointer to a `QkValue`. **Parameters** - **value** – A pointer to a duration value. **Returns** A `QkDurationInfo` struct containing the duration unit and raw value. ### qk\_value\_float `double qk_value_float(const QkValue *value)` Extract the floating-point value from a `QkValue`. Panics if `value` does not point to a float value. #### Example ```c double raw = qk_value_float(value); ``` #### Safety Behavior is undefined if `value` is not a valid, non-null pointer to a `QkValue`. **Parameters** - **value** – A pointer to a float value. **Returns** The `double` value stored in `value`. ### qk\_value\_uint `uint64_t qk_value_uint(const QkValue *value)` Extract the unsigned integer value from a `QkValue` of type `QkExprType_Uint`. you should use `qk_value_type_info` to ensure the value will fit in `uint64_t` before calling this function. Panics if `value` does not point to a `QkExprType_Uint` value or if the stored integer does not fit in `uint64_t`. #### Example ```c uint64_t raw = qk_value_uint(value); ``` #### Safety Behavior is undefined if `value` is not a valid, non-null pointer to a `QkValue`. **Parameters** - **value** – A pointer to a uint value. **Returns** The integer value converted to `uint64_t`. ### qk\_value\_bool `bool qk_value_bool(const QkValue *value)` Extract the value from a `QkValue` of type `QkExprType_Bool`. Panics if `value` does not point to a bool value. #### Example ```c bool raw = qk_value_bool(value); ``` #### Safety Behavior is undefined if `value` is not a valid, non-null pointer to a `QkValue`. **Parameters** - **value** – A pointer to a bool value. **Returns** `true` if the stored integer representation is nonzero, otherwise `false`. ### qk\_var\_name `char *qk_var_name(const QkVar *var)` Return the name of a variable as a newly allocated C string. #### Example ```c char *name = qk_var_name(var); if (name != NULL) { // Use the name... qk_str_free(name); } ``` #### Safety Behavior is undefined if `var` is not a valid, non-null pointer to a `QkVar`. **Parameters** - **var** – A pointer to the variable to inspect. **Returns** A null-terminated string containing the variable name, or `NULL` if `var` refers to a non-standalone variable (i.e. based on a classical bit or a classical register). The caller owns the returned string and must free it with `qk_str_free`. ### qk\_var\_type\_info `QkExprTypeInfo qk_var_type_info(const QkVar *var)` Return full type information for a variable. Panics if `var` is a bit variable, which is not yet supported by this API. #### Example ```c QkExprTypeInfo type_info = qk_var_type_info(var); ``` #### Safety Behavior is undefined if `var` is not a valid, non-null pointer to a `QkVar`. **Parameters** - **var** – A pointer to the variable to inspect. **Returns** A `QkExprTypeInfo` struct containing the variable type information. ### qk\_stretch\_name `char *qk_stretch_name(const QkStretch *stretch)` Return the name of a stretch. #### Example ```c char *name = qk_stretch_name(stretch); // Use the name... qk_str_free(name); ``` #### Safety Behavior is undefined if `stretch` is not a valid, non-null pointer to a `QkStretch`. **Parameters** - **stretch** – A pointer to the stretch to inspect. **Returns** A null-terminated string containing the stretch name. The caller owns the returned string and must free it with `qk_str_free`.