Skip to main content
IBM Quantum Platform

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 <types.h>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Was this page helpful?
Report a bug, typo, or request content on GitHub.