Skip to main contentIBM Quantum Documentation Mirror

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.

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 representing complex values the real part is returned.

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.