--- title: QkParam (latest version) description: API reference for QkParam in the latest version of qiskit-c source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-c/qk-param --- # 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`](/docs/api/qiskit/qiskit.circuit.Parameter#qiskit.circuit.Parameter "qiskit.circuit.Parameter"). ## Functions ### qk\_param\_new\_symbol `QkParam *qk_param_new_symbol(const char *name)` Construct a new `QkParam` representing an unbound symbol. #### Example ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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`.