cuStateVec (cuquantum.bindings.custatevec)#

Python objects & constants#

Objects#

SVSwapParameters()

A wrapper class holding a set of data transfer parameters.

sv_swap_parameters_dtype

NumPy dtype object that encapsulates the sv swap parameters in bindings.custatevec.

Enums and constants#

Pauli(value)

Constants to specify Pauli basis:

MatrixLayout(value)

Constants to specify a matrix's memory layout.

MatrixType(value)

Constants to specify the matrix type.

MatrixMapType(value)

Constants to specify how to assign matrices to batched state vectors.

CollapseOp(value)

Constants to specify collapse operations.

SamplerOutput(value)

Constants to specify the order of bit strings in sampling outputs.

DeviceNetworkType(value)

Constants to specify the device network topology.

StateVectorType(value)

Constants to specify the quantum state.

MathMode(value)

Constants to specify the compute precision mode.

CommunicatorType(value)

Constant to specify the communicator used in inter-process communications.

DataTransferType(value)

Constant to specify the data transfer direction in point-to-point communication.

Python functions#

Library management#

Handle management API#

create()

This function initializes the cuStateVec library and creates a handle on the cuStateVec context.

destroy(intptr_t handle)

This function releases resources used by the cuStateVec library.

get_default_workspace_size(intptr_t handle)

This function returns the default workspace size defined by the cuStateVec library.

set_workspace(intptr_t handle, ...)

This function sets the workspace used by the cuStateVec library.

CUDA stream management API#

set_stream(intptr_t handle, intptr_t stream_id)

This function sets the stream to be used by the cuStateVec library to execute its routine.

get_stream(intptr_t handle)

This function gets the cuStateVec library stream used to execute all calls from the cuStateVec library functions.

Logger API#

logger_set_callback_data(callback, *args, ...)

Set the logger callback along with arguments.

logger_open_file(log_file)

Experimental: This function opens a logging output file in the given path.

logger_set_level(int32_t level)

Experimental: This function sets the value of the logging level.

logger_set_mask(int32_t mask)

Experimental: This function sets the value of the logging mask.

logger_force_disable()

Experimental: This function disables logging for the entire run.

Memory management API#

set_device_mem_handler(intptr_t handle, handler)

Set the device memory handler for cuStateVec.

get_device_mem_handler(intptr_t handle)

Get the device memory handler for cuStateVec.

Versioning API#

get_property(int type)

This function returns the version information of the cuStateVec library.

get_version()

This function returns the version information of the cuStateVec library.

Math mode API#

set_math_mode(intptr_t handle, int mode)

Set the compute precision mode.

get_math_mode(intptr_t handle)

Get the current compute precision mode.

State vector initialization#

initialize_state_vector(intptr_t handle, ...)

Initialize the state vector to a certain form.

Gate application#

General matrices#

apply_matrix_get_workspace_size(...)

This function gets the required workspace size for apply_matrix().

apply_matrix(intptr_t handle, intptr_t sv, ...)

Apply gate matrix.

apply_matrix_batched_get_workspace_size(...)

This function gets the required workspace size for apply_matrix_batched().

apply_matrix_batched(intptr_t handle, ...)

This function applies one gate matrix to each one of a set of batched state vectors.

Pauli matrices#

apply_pauli_rotation(intptr_t handle, ...)

Apply the exponential of a multi-qubit Pauli operator.

Generalized permutation matrices#

apply_generalized_permutation_matrix_get_workspace_size(...)

Get the extra workspace size required by apply_generalized_permutation_matrix().

apply_generalized_permutation_matrix(...)

Apply generalized permutation matrix.

Measurement#

Measurement on Z-bases#

abs2sum_on_z_basis(intptr_t handle, ...)

Calculates the sum of squared absolute values on a given Z product basis.

collapse_on_z_basis(intptr_t handle, ...)

Collapse state vector on a given Z product basis.

measure_on_z_basis(intptr_t handle, ...)

Measurement on a given Z-product basis.

Qubit measurement#

abs2sum_array(intptr_t handle, intptr_t sv, ...)

Calculate abs2sum array for a given set of index bits.

collapse_by_bit_string(intptr_t handle, ...)

Collapse state vector to the state specified by a given bit string.

batch_measure(intptr_t handle, intptr_t sv, ...)

Batched single qubit measurement.

abs2sum_array_batched(intptr_t handle, ...)

Calculate batched abs2sum array for a given set of index bits.

collapse_by_bit_string_batched_get_workspace_size(...)

This function gets the required workspace size for collapse_by_bit_string_batched().

collapse_by_bit_string_batched(...)

Collapse the batched state vectors to the state specified by a given bit string.

measure_batched(intptr_t handle, ...)

Single qubit measurements for batched state vectors.

batch_measure_with_offset(intptr_t handle, ...)

Batched single qubit measurement for partial vector.

Expectation#

Expectation via a matrix#

compute_expectation_get_workspace_size(...)

This function gets the required workspace size for compute_expectation().

compute_expectation(intptr_t handle, ...)

Compute expectation of matrix observable.

compute_expectation_batched_get_workspace_size(...)

This function gets the required workspace size for compute_expectation_batched().

compute_expectation_batched(intptr_t handle, ...)

Compute the expectation values of matrix observables for each of the batched state vectors.

Expectation on Pauli basis#

compute_expectations_on_pauli_basis(...)

Calculate expectation values for a batch of (multi-qubit) Pauli operators.

Sampling#

sampler_create(intptr_t handle, intptr_t sv, ...)

Create sampler descriptor.

sampler_destroy(intptr_t sampler)

This function releases resources used by the sampler.

sampler_preprocess(intptr_t handle, ...)

Preprocess the state vector for preparation of sampling.

sampler_sample(intptr_t handle, ...)

Sample bit strings from the state vector.

sampler_get_squared_norm(intptr_t handle, ...)

Get the squared norm of the state vector.

sampler_apply_sub_sv_offset(intptr_t handle, ...)

Apply the partial norm and norm to the state vector to the sample descriptor.

Accessor#

accessor_create(intptr_t handle, ...)

Create accessor to copy elements between the state vector and an external buffer.

accessor_create_view(intptr_t handle, ...)

Create accessor for the constant state vector.

accessor_destroy(intptr_t accessor)

This function releases resources used by the accessor.

accessor_set_extra_workspace(...)

Set the external workspace to the accessor.

accessor_get(intptr_t handle, ...)

Copy state vector elements to an external buffer.

accessor_set(intptr_t handle, ...)

Set state vector elements from an external buffer.

Single-process qubit reordering#

swap_index_bits(intptr_t handle, ...)

Swap index bits and reorder statevector elements on the device.

multi_device_swap_index_bits(handles, ...)

Swap index bits and reorder statevector elements on multiple devices.

Multi-process qubit reordering#

communicator_create(intptr_t handle, ...)

Create communicator.

communicator_destroy(intptr_t handle, ...)

This function releases communicator.

dist_index_bit_swap_scheduler_create(...)

Create distributed index bit swap scheduler.

dist_index_bit_swap_scheduler_destroy(...)

This function releases distributed index bit swap scheduler.

dist_index_bit_swap_scheduler_set_index_bit_swaps(...)

Schedule the index bits to be swapped across processes.

dist_index_bit_swap_scheduler_get_parameters(...)

Get the data transfer parameters from the scheduler.

sv_swap_worker_create(intptr_t handle, ...)

Create state vector swap worker.

sv_swap_worker_destroy(intptr_t handle, ...)

This function releases the state vector swap worker.

sv_swap_worker_set_extra_workspace(...)

Set extra workspace.

sv_swap_worker_set_transfer_workspace(...)

Set transfer workspace.

sv_swap_worker_set_sub_svs_p2p(...)

Set sub state vector pointers accessible via GPUDirect P2P with CUDA IPC events.

sv_swap_worker_set_parameters(...)

Set data transfer parameters for the distributed sub statevector swap workers.

sv_swap_worker_execute(intptr_t handle, ...)

Execute the data transfer.

Sub state vector migration#

sub_sv_migrator_create(intptr_t handle, ...)

Create sub state vector migrator descriptor.

sub_sv_migrator_destroy(intptr_t handle, ...)

Destroy sub state vector migrator descriptor.

sub_sv_migrator_migrate(intptr_t handle, ...)

Sub state vector migration.

Test gate matrix type#

test_matrix_type_get_workspace_size(...)

Get extra workspace size for test_matrix_type().

test_matrix_type(intptr_t handle, ...)

Test the deviation of a given matrix from a Hermitian (or Unitary) matrix.