QkParam

Represents a circuit parameter which may hold real or symbolic values.

While functionality for a QkParam within a circuit is currently limited, a user is able to perform operations similar to the ones present in Parameter.

Data Types

QkParamKind

enum QkParamKind

Represents the type of a QkParam instance.

Values:

enumerator QkParamKind_Unknown

Represents an unknown parameter that is not representable in the C API. Typically this is a parameter that is defined in Python.

enumerator QkParamKind_Real

Represents a real floating point parameter.

enumerator QkParamKind_ParameterExpression

Represents an unbound parameter symbol.

enumerator QkParamKind_Int

Represents a parameter that can only be represented by an integer. Usually a duration in terms of Dt.

Functions

qk_param_new_symbol

QkParam *qk_param_new_symbol(const char *name)

Construct a new QkParam representing an unbound symbol.

Example

QkParam *a = qk_param_new_symbol("a");

Safety

The name parameter must be a pointer to memory that contains a valid nul terminator at the end of the string. It also must be valid for reads of bytes up to and including the nul terminator.

Parameters

name – The name of symbol. This cannot be empty.

Returns

A pointer to the created QkParam.

qk_param_zero

QkParam *qk_param_zero(void)

Construct a new QkParam with a value zero.

The QkParam returned from this function can be used to store the result of binary or unary operations.

Example

QkParam *t = qk_param_zero();
QkParam *a = qk_param_new_symbol("a");
QkParam *b = qk_param_new_symbol("b");
qk_param_add(t, a, b);

Returns

A pointer to the created QkParam.

qk_param_free

void qk_param_free(QkParam *param)

Free the QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
qk_param_free(a);

Safety

Behavior is undefined if param is not either null or a valid pointer to a QkParam.

Parameters

param – A pointer to the QkParam to free.

qk_param_from_double

QkParam *qk_param_from_double(double value)

Construct a new QkParam from a double.

Example

QkParam *r = qk_param_from_double(2.5);

Parameters

value – A double to initialize the QkParam.

Returns

A pointer to the created QkParam.

qk_param_from_complex

QkParam *qk_param_from_complex(QkComplex64 value)

Construct a new QkParam from a complex number, given as QkComplex64.

Example

QkComplex64 c = {1.0, 2.0};  // 1 + 2i
QkParam *param = qk_param_from_complex(c);

Parameters

value – A QkComplex64 to initialize the QkParam.

Returns

A pointer to the created QkParam.

qk_param_copy

QkParam *qk_param_copy(const QkParam *param)

Copy a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *b = qk_param_copy(a);

Safety

The behavior is undefined if param is not a valid pointer to a non-null QkParam.

Parameters

param – The QkParam to copy.

Returns

A pointer to the created QkParam.

qk_param_str

char *qk_param_str(const QkParam *param)

Get a string representation of the QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
char* str = qk_param_str(a);
printf(str);
qk_str_free(str);
qk_param_free(a);

Safety

The behavior is undefined if param is not a valid pointer to a non-null QkParam.

The string must not be freed with the normal C free, you must use qk_str_free to free the memory consumed by the String. Not calling qk_str_free will lead to a memory leak.

Do not change the length of the string after it’s returned (by writing a nul byte somewhere inside the string or removing the final one), although values can be mutated.

Parameters

param – A pointer to the QkParam.

Returns

A pointer to a nul-terminated char array of the string representation for param.

qk_param_add

QkExitCode qk_param_add(QkParam *out, const QkParam *lhs, const QkParam *rhs)

Add two QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *b = qk_param_new_symbol("b");
QkParam *out = qk_param_zero();
qk_param_add(out, a, b);

Safety

The behavior is undefined if any of out, lhs or rhs is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result of lhs + rhs.
lhs – A pointer to the left hand side QkParam.
rhs – A pointer to the right hand side QkParam.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_sub

QkExitCode qk_param_sub(QkParam *out, const QkParam *lhs, const QkParam *rhs)

Subtract two QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *b = qk_param_new_symbol("b");
QkParam *out = qk_param_zero();
qk_param_sub(out, a, b);

Safety

The behavior is undefined if any of out, lhs or rhs is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to a QkParam to store the result of lhs - rhs.
lhs – A pointer to the left hand side QkParam.
rhs – A pointer to the right hand side QkParam.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_mul

QkExitCode qk_param_mul(QkParam *out, const QkParam *lhs, const QkParam *rhs)

Multiply two QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *b = qk_param_new_symbol("b");
QkParam *out = qk_param_zero();
qk_param_mul(out, a, b);

Safety

The behavior is undefined if any of out, lhs or rhs is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to a QkParam to store the result of lhs * rhs.
lhs – A pointer to the left hand side QkParam.
rhs – A pointer to the right hand side QkParam.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_div

QkExitCode qk_param_div(QkParam *out, const QkParam *num, const QkParam *den)

Divide a QkParam by another.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *b = qk_param_new_symbol("b");
QkParam *out = qk_param_zero();
qk_param_div(out, a, b);

Safety

The behavior is undefined if any of out, num or den is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to a QkParam to store the result of lhs / rhs.
num – A pointer to the numerator QkParam.
den – A pointer to the denominator QkParam.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_pow

QkExitCode qk_param_pow(QkParam *out, const QkParam *base, const QkParam *pow)

Raise a QkParam to the power of another.

Example

QkParam *base = qk_param_new_symbol("a");
QkParam *pow = qk_param_new_symbol("b");
QkParam *out = qk_param_zero();
qk_param_pow(out, base, pow);

Safety

The behavior is undefined if any of out, base or pow is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to a QkParam to store the result of lhs ** rhs.
base – A pointer to the left hand side QkParam.
pow – A pointer to the right hand side QkParam.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_sin

QkExitCode qk_param_sin(QkParam *out, const QkParam *src)

Calculate the sine of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_sin(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, sin(src).
src – A pointer to the QkParam to apply the sine to.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_cos

QkExitCode qk_param_cos(QkParam *out, const QkParam *src)

Calculate the cosine of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_cos(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, cos(src).
src – A pointer to the QkParam to apply the cosine to.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_tan

QkExitCode qk_param_tan(QkParam *out, const QkParam *src)

Calculate the tangent of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_tan(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, tan(src).
src – A pointer to the QkParam to apply the tangent to.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_asin

QkExitCode qk_param_asin(QkParam *out, const QkParam *src)

Calculate the arcsine of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_asin(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, asin(src).
src – A pointer to the QkParam to apply the arcsine to.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_acos

QkExitCode qk_param_acos(QkParam *out, const QkParam *src)

Calculate the arccosine of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_acos(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, acos(src).
src – A pointer to the QkParam to apply the cosine to.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_atan

QkExitCode qk_param_atan(QkParam *out, const QkParam *src)

Calculate the arctangent of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_atan(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store a result, atan(src).
src – A pointer to the QkParam to apply the arctangent to.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_log

QkExitCode qk_param_log(QkParam *out, const QkParam *src)

Calculate the natural logarithm of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_log(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, log(src).
src – A pointer to the QkParam to apply the logarithm to.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_exp

QkExitCode qk_param_exp(QkParam *out, const QkParam *src)

Apply the exponential function to a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_exp(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, exp(src).
src – A pointer to the QkParam to compute the exponential of.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_abs

QkExitCode qk_param_abs(QkParam *out, const QkParam *src)

Calculate the absolute value of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_abs(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store a result.
src – A pointer to the QkParam.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_sign

QkExitCode qk_param_sign(QkParam *out, const QkParam *src)

Get the sign of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_sign(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, sign(src).
src – A pointer to the QkParam to get the sign of.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_neg

QkExitCode qk_param_neg(QkParam *out, const QkParam *src)

Negate a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_neg(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, -src.
src – A pointer to the QkParam to negate.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_conjugate

QkExitCode qk_param_conjugate(QkParam *out, const QkParam *src)

Calculate the complex conjugate of a QkParam.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *out = qk_param_zero();
qk_param_conjugate(out, a);

Safety

The behavior is undefined if any of out or src is not a valid, non-null pointer to a QkParam.

Parameters

out – A pointer to the QkParam to store the result, conj(src).
src – A pointer to the QkParam to conjugate.

Returns

An exit code indicating QkExitCode_Success upon success and an error otherwise.

qk_param_equal

bool qk_param_equal(const QkParam *lhs, const QkParam *rhs)

Compare two QkParam for equality.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *one = qk_param_from_value(1.0);
QkParam *mone = qk_param_from_value(-1.0);

QkParam *x = qk_param_add(a, one);
QkParam *y = qk_param_sub(a, mone);

bool equal = qk_param_equal(x, y);

Safety

The behavior is undefined if any of lhs or rhs is not a valid, non-null pointer to a QkParam.

Parameters

lhs – A pointer to the left hand side QkParam.
rhs – A pointer to the right hand side QkParam.

Returns

true if the QkParam objects are equal, false otherwise.

qk_param_as_real

double qk_param_as_real(const QkParam *param)

Attempt casting the QkParam as double.

If the parameter could not be cast to a double, because there were unbound parameters, NAN is returned. Note that for QkParam of the kind QkParamKind_ParameterExpression representing a bound complex values the real part is returned.

If the parameter in originally an int instance, it will be coerced into a double, resulting in a lossy conversion.

Example

QkParam *a = qk_param_new_symbol("a");
QkParam *b = qk_param_new_symbol("b");
QkParam *x = qk_param_zero();
qk_param_add(x, a, b);

const QkParam* keys[2] = {a, b};
QkParam *y = qk_param_zero();
qk_param_bind(y, x, keys, {1.0, 2.0}, 2);

double out = qk_param_as_real(y);

Safety

The behavior is undefined if param is not a valid, non-null pointer to a QkParam.

Parameters

param – A pointer to the QkParam to evaluate.

Returns

The value, if casting was successful, otherwise NAN.

qk_param_stride

size_t qk_param_stride(void)

Get the size in bytes of the opaque QkParam type.

The QkParam type is opaque to the C API, and its width is unspecified. You can use this value to offset QkParam * pointers, if you cast it to a byte-width type and back.

This function returns the same value on every call within any given process. The value might change between platforms or Qiskit library versions, and may depend on the build environment of the Qiskit C API. You must not rely on this width being any particular value without querying this function.

Example

If given a pointer to the first QkParam in a contiguous array, such as in QkCircuitInstructionView::params, you can access subsequent elements by offsetting the pointer by a number of bytes.

const QkParam *p;  // A pretend pointer to the first of 3 contiguous elements.
const size_t el_size = qk_param_stride();
for (size_t i = 0; i < 3; i++) {
// Offset the pointer by `el_size` bytes each time.
    p = (const QkParam *)((const char *)p + el_size);

char *val = qk_param_str(p);
    printf("%zu: %s\n", i, val);
qk_str_free(val);
}

Returns

The size in bytes of the opaque QkParam type.

qk_param_as_int

bool qk_param_as_int(const QkParam *param, int64_t *value)

Attempt casting the QkParam as int64_t. This is intended to be used for retrieving a parameter representing the duration of a delay instruction in units of Dt.

If the parameter could not be cast to a int64_t, because there were unbound parameters, the pointer will not be written to and the function will return false. This will also be the case if the parameter is bound but evaluates to a floating point or complex number.

Safety

The behavior is undefined if param is not a valid, non-null pointer to a QkParam. The behavior is undefined if value is not a valid, non-null pointer to an address that can hold an int64_t instance.

Parameters

param – A pointer to the QkParam to evaluate.
value – A pointer to a int64_t to write the resulting value.

Returns

true if the stored value is an integer, otherwise false.

qk_param_kind

QkParamKind qk_param_kind(const QkParam *param)

Returns the associated type of the QkParam instance via the QkParamKind enumeration.

Safety

The behavior is undefined if param is not a valid, non-null pointer to a QkParam.

Parameters

param – A pointer to the QkParam to evaluate.

Returns

The associated type with the parameter.

このページは役に立ちましたか？

バグや誤字の報告、またはコンテンツの要求はGitHubで行ってください。