API Reference

This part of the documentation lists all the functions provided by Parament.

C API

Functions

Parament_ErrorCode Parament_create(struct Parament_Context_f32 **handle_p)

Create a new Parament context.

The context must eventually be destroyed by calling Parament_destroy().

Parameters

handle_p – The new context.

Returns

PARAMENT_STATUS_SUCCESS on success.
PARAMENT_STATUS_HOST_ALLOC_FAILED when an underlying call to malloc() failed.
PARAMENT_STATUS_CUBLAS_INIT_FAILED when Parament fails to initialize a cuBLAS context.
PARAMENT_STATUS_DEVICE_ALLOC_FAILED when a call to cudaMalloc() failed.
PARAMENT_FAIL when an unknown error occurred.

Return type

Parament_ErrorCode

See also

Parament_create_fp64(): The double precision variant

Parament_ErrorCode Parament_destroy(struct Parament_Context_f32 *handle)

Destroy the context previously created with Parament_create().

If the provided handle is NULL, this function does nothing. Using a context after it has been destroyed results in undefined behaviour.

Parameters

handle – The context to destroy.

Returns

PARAMENT_STATUS_SUCCESS on success.

Return type

Parament_ErrorCode

See also

Parament_destroy_fp64(): The double precision variant

Parament_ErrorCode Parament_setHamiltonian(struct Parament_Context_f32 *handle, cuComplex *H0, cuComplex *H1, unsigned int dim, unsigned int amps, _Bool use_magnus, enum Parament_QuadratureSpec quadrature_mode)

Load the drift and control Hamiltonians.

TODO: specifiy ordering of H0, H1

Parameters

handle – Handle to the Parament context.
H0 – Drift Hamiltionian. Must be dim x dim array.
H1 – Interaction Hamiltonians. Must be dim x dim x amps array.
dim – Dimension of the Hamiltonians.
amps – Number of the control amplitudes.
use_magnus – Enable or disable the 1st order Magnus expansion. When true, pass PARAMENT_QUADRATURE_SIMPSON as quadrature_mode.
quadrature_mode –
The quadrature rule used for interpolating the control amplitudes.

Returns

PARAMENT_STATUS_SUCCESS on success.
PARAMENT_STATUS_DEVICE_ALLOC_FAILED when allocation of memory on the accelerator device failed.
PARAMENT_STATUS_CUBLAS_FAILED when an underlying cuBLAS operation failed.
PARAMENT_STATUS_INVALID_QUADRATURE_SELECTION when passing use_magnus=True without also passing PARAMENT_QUADRATURE_SIMPSON as quadrature_mode.

Return type

Parament_ErrorCode

See also

Parament_setHamiltonian_fp64(): The double precision variant

Parament_ErrorCode Parament_equiprop(struct Parament_Context_f32 *handle, cuComplex *carr, double dt, unsigned int pts, unsigned int amps, cuComplex *out)

Compute the propagator from the Hamiltionians.

The control fields waveforms are specified via the parameter carr. This must be an array of length pts*amps, laid out in memory as a concatenation of amps arrays with length pts each.

The number of control fields amps must not exceed the value previously set before with Parament_setHamiltonian(), otherwise behaviour is undefined. It may be less, in which case the extra Hamiltonians are assumed to have zero amplitude.

Parameters

context – Handle to the Parament context.
carr – Array of the control field amplitudes.
dt – Duration of a time step.
pts – Number of time steps.
amps – Number of control Hamiltonians.
out – The returned propagator.

Returns

PARAMENT_STATUS_SUCCESS on success.
PARAMENT_STATUS_NO_HAMILTONIAN when no Hamiltonian has been loaded (see Parament_setHamiltonian()).
PARAMENT_STATUS_SELECT_SMALLER_DT when automatic iteration count is enabled, and convergence would require an excessive number of iterations. Reduce the time step dt.
PARAMENT_STATUS_DEVICE_ALLOC_FAILED when allocation of memory on the accelerator device failed.
PARAMENT_STATUS_CUBLAS_FAILED when an underlying cuBLAS operation failed.

Return type

Parament_ErrorCode

See also

Parament_equiprop_fp64(): The double precision variant

Parament_ErrorCode Parament_automaticIterationCycles(struct Parament_Context_f32 *handle)

Reenable the automatic choice of the number of iteration cycles used for the Chebychev approximation.

Parameters

handle – Handle to the Parament context.

Returns

PARAMENT_STATUS_SUCCESS on success.

Return type

Parament_ErrorCode

See also

Parament_automaticIterationCycles_fp64(): The double precision variant

int Parament_selectIterationCycles_fp32(double H_norm, double dt)

Get the number of Chebychev cycles necessary for reaching machine precision.

The iteration count depends on the the given Hamiltonian and the given evolution time.

Parameters

H_norm – Operator norm of the Hamiltonian.
dt – Time step.

Returns

The required iteration count. Returns -1 if the product of norm and dt is too large, and convergence cannot be guaranteed within a reasonable iteration count.

Return type

int

See also

selectIterationCycles_fp64(): The double precision variant

Parament_ErrorCode Parament_setIterationCyclesManually(struct Parament_Context_f32 *handle, unsigned int cycles)

Manually enforce the number of iteration cycles used for the Chebychev approximation.

Parameters

handle – Handle to the Parament context.
cycles – Number of iteration cycles.

Returns

PARAMENT_STATUS_SUCCESS on success.

Return type

Parament_ErrorCode

See also

Parament_automaticIterationCycles(): Restore the default behaviour.
Parament_setIterationCyclesManually_fp64(): The double precision variant

const char *Parament_errorMessage(Parament_ErrorCode errorCode)

Get human readable message from error code.

Parameters

errorCode – Error code for which to retrieve a message.

Parament_ErrorCode Parament_peekAtLastError(struct Parament_Context_f32 *handle)

Query the last error code.

Parameters

handle – Handle to the Parament context.

Returns

The error code returned by the last Parament call. Parament_peekAtLastError() itself does not overwrite the error code.

Return type

Parament_ErrorCode

See also

Parament_peekAtLastError_fp64(): The double precision variant

Double-precision functions

Parament_ErrorCode Parament_create_fp64(struct Parament_Context_f64 **handle_p): Double-precision version of Parament_create().

Parament_ErrorCode Parament_destroy_fp64(struct Parament_Context_f64 *handle): Double-precision version of Parament_destroy().

Parament_ErrorCode Parament_equiprop_fp64(struct Parament_Context_f64 *handle, cuDoubleComplex *carr, double dt, unsigned int pts, unsigned int amps, cuDoubleComplex *out): Double-precision version of Parament_equiprop().

Parament_ErrorCode Parament_setHamiltonian_fp64(struct Parament_Context_f64 *handle, cuDoubleComplex *H0, cuDoubleComplex *H1, unsigned int dim, unsigned int amps, _Bool use_magnus, Parament_QuadratureSpec quadrature_mode): Double-precision version of Parament_setHamiltonian().

Parament_ErrorCode Parament_automaticIterationCycles_fp64(struct Parament_Context_f64 *handle): Double-precision version of Parament_automaticIterationCycles().

Parament_ErrorCode Parament_peekAtLastError_fp64(struct Parament_Context_f64 *handle): Double-precision version of Parament_peekAtLastError().

int Parament_selectIterationCycles_fp64(double H_norm, double dt): Double-precision version of Parament_selectIterationCycles_fp32().

Parament_ErrorCode Parament_setIterationCyclesManually_fp64(struct Parament_Context_f64 *handle, unsigned int cycles): Double-precision version of Parament_setIterationCyclesManually().

Constants

enum Parament_QuadratureSpec

Quadrature rule used by Parament_setHamiltonian().

enumerator PARAMENT_QUADRATURE_NONE = 0x00000000: No quadrature rule.

enumerator PARAMENT_QUADRATURE_MIDPOINT = 0x01000000: Apply midpoint rule.

enumerator PARAMENT_QUADRATURE_SIMPSON = 0x02000000: Apply Simpson’s rule.

enum Parament_ErrorCode

Error codes returned by Parament.

enumerator PARAMENT_STATUS_SUCCESS = 0: No error

enumerator PARAMENT_STATUS_HOST_ALLOC_FAILED = 10: Memory allocation on the host failed. This is usually a failure of malloc(). The machine is likely running out of memory. Deallocate memory that is no longer needed.

enumerator PARAMENT_STATUS_DEVICE_ALLOC_FAILED = 20: Memory allocation on the device failed. This error usually arises from a failure of cudaMalloc(). Deallocate memory that is no longer needed.

enumerator PARAMENT_STATUS_CUBLAS_INIT_FAILED = 30: Failed to initialize the cuBLAS library.

enumerator PARAMENT_STATUS_INVALID_VALUE = 50: Trying to call a Parament function with an illegal value.

enumerator PARAMENT_STATUS_CUBLAS_FAILED = 60: Failed to execute cuBLAS function.

enumerator PARAMENT_STATUS_SELECT_SMALLER_DT = 70: Failed to perform automatic iteration cycles determination.

enumerator PARAMENT_STATUS_NO_HAMILTONIAN = 80: Trying to call Parament_equiprop() without having loaded a Hamiltonian via Parament_setHamiltonian().

enumerator PARAMENT_STATUS_INVALID_QUADRATURE_SELECTION = 90: Failed to perform automatic iteration cycles determination.

enumerator PARAMENT_FAIL = 1000: Place holder for more error codes…

Python API

class Parament(precision='fp32')[source]

Create a new Parament context.

The context stores settings and state between function calls. Use setHamiltonian() to load the Hamiltonians, and then call equiprop() to compute the propagator.

Parameters: precision ({'fp32', 'fp64'}) – The native precision of the new context.

Examples

>>> gpu_runner = parament.Parament()
>>> H0 = np.array([[1, 0], [0, -1]])
>>> H1 = np.array([[0, 1], [1, 0]])
>>> dt = 1.0
>>> gpu_runner.set_hamiltonian(H0, H1)
>>> gpu_runner.equiprop(dt, np.zeros(1))
array([[0.54030234-0.84147096j, 0.        +0.j        ],
   [0.        +0.j        , 0.54030234+0.84147096j]], dtype=complex64)

To release the resources allocated by the context, call the destroy() method. This happens automatically if the context object is garbage collected by the interpreter. Good practice nevertheless mandates proper and explicit lif cycle management.

If the context is only to be short lived, the recommended way is to use it as a context manager.

>>> with parament.Parament() as gpu_runner:
...     gpu_runner.set_hamiltonian(H0, H1)
...     gpu_runner.equiprop(dt, np.zeros(1))
array([[0.54030234-0.84147096j, 0.        +0.j        ],
   [0.        +0.j        , 0.54030234+0.84147096j]], dtype=complex64)

The with statement guarantees that the context is properly destroyed, even in the event of an exception.

See also

Parament_create(): The underlying core function.

destroy()[source]

Destroy the context. Will implicitly be called when the object is garbage-collected.

See also

Parament_destroy(): The underlying core function.

equiprop(dt, *carr)[source]

Compute the propagator from the Hamiltionians.

The carr argument is variadic. In the case of multiple control fields, just pass one vector per control Hamoltonian. For example, if u1 and u2 are the amplitudes for two Hamiltonians:

>>> equiprop(dt, u1, u2)

If instead you have a 2D array (where the first axis indexes the fields, and the second axis denotes time), or a list/tuple of vectors, you can conveniently unpack it with the * operator. For instance, the above call is equivalent to:

>>> carr = u1, u2
>>> equiprop(dt, *carr)

Parameters

dt (float) – Time step.
*carr (ndarrray) – Array of the control field amplitudes.

Returns

The computed propagator

Return type

ndarray

See also

Parament_equiprop(): The underlying core function.

set_hamiltonian(H0, *H1, use_magnus=False, quadrature_mode='none')[source]

Load the hamiltonians.

The drift Hamiltonian H0 can bei either a numpy ndarray or a qutip object. In the latter case, subsequent calls to equiprop() will also return a qutip object.

The parameter H1 is variadic, i.e. you can pass multiple matrices:

>>> Parament.set_hamiltonian(H0, H1, H2)

If you have a list (or tuple) of the control Hamiltonians, pass them like so:

>>> H_control = (H1, H2)
>>> Parament.set_hamiltonian(H0, *H_control)

This even works if H_control is not a tuple or a list, but a single 3D ndarray, where the first axis enumerates the hamiltonians.

Note that because H1 is variadic, any following arguments (use_use_magnus and quadrature_mode) can only be passed by keyword.

Parameters

H0 (ndarray or qutip object) – Drift Hamiltionian.
*H1 (ndarray, qutip object or list of either one) – Interaction Hamiltonians.
use_magnus (bool) – Enable or disable the 1st order Magnus expansion. When true, pass ‘simpson’ as quadrature_mode.
quadrature_mode ({'none', 'midpoint', 'simpson'}) – The quadrature rule used for interpolating the control amplitudes.

See also

Parament_setHamiltonian(): The underlying core function.

Parament User guide