cuTensorNet Functions ********************* .. role:: raw-html(raw) :format: html Handle Management API ===================== .. _cutensornetCreate-label: :code:`cutensornetCreate` ------------------------- .. doxygenfunction:: cutensornetCreate ---- .. _cutensornetDestroy-label: :code:`cutensornetDestroy` -------------------------- .. doxygenfunction:: cutensornetDestroy ---- Network Descriptor API ====================== .. _cutensornetCreateNetworkDescriptor-label: :code:`cutensornetCreateNetworkDescriptor` ------------------------------------------ .. doxygenfunction:: cutensornetCreateNetworkDescriptor ---- .. _cutensornetDestroyNetworkDescriptor-label: :code:`cutensornetDestroyNetworkDescriptor` ------------------------------------------- .. doxygenfunction:: cutensornetDestroyNetworkDescriptor ---- .. _cutensornetNetworkGetAttribute-label: :code:`cutensornetNetworkGetAttribute` ------------------------------------------- .. doxygenfunction:: cutensornetNetworkGetAttribute ---- .. _cutensornetNetworkSetAttribute-label: :code:`cutensornetNetworkSetAttribute` ------------------------------------------- .. doxygenfunction:: cutensornetNetworkSetAttribute ---- .. _cutensornetGetOutputTensorDetails-label: :code:`cutensornetGetOutputTensorDetails` ----------------------------------------- .. doxygenfunction:: cutensornetGetOutputTensorDetails ---- .. _cutensornetGetOutputTensorDescriptor-label: :code:`cutensornetGetOutputTensorDescriptor` -------------------------------------------- .. doxygenfunction:: cutensornetGetOutputTensorDescriptor ---- Tensor Descriptor API ===================== .. _cutensornetCreateTensorDescriptor-label: :code:`cutensornetCreateTensorDescriptor` ----------------------------------------- .. doxygenfunction:: cutensornetCreateTensorDescriptor ---- .. _cutensornetGetTensorDetails-label: :code:`cutensornetGetTensorDetails` ----------------------------------- .. doxygenfunction:: cutensornetGetTensorDetails ---- .. _cutensornetDestroyTensorDescriptor-label: :code:`cutensornetDestroyTensorDescriptor` ------------------------------------------ .. doxygenfunction:: cutensornetDestroyTensorDescriptor ---- Contraction Optimizer API ========================= .. _cutensornetCreateContractionOptimizerConfig-label: :code:`cutensornetCreateContractionOptimizerConfig` --------------------------------------------------- .. doxygenfunction:: cutensornetCreateContractionOptimizerConfig ---- .. _cutensornetDestroyContractionOptimizerConfig-label: :code:`cutensornetDestroyContractionOptimizerConfig` ---------------------------------------------------- .. doxygenfunction:: cutensornetDestroyContractionOptimizerConfig ---- .. _cutensornetContractionOptimizerConfigGetAttribute-label: :code:`cutensornetContractionOptimizerConfigGetAttribute` --------------------------------------------------------- .. doxygenfunction:: cutensornetContractionOptimizerConfigGetAttribute ---- .. _cutensornetContractionOptimizerConfigSetAttribute-label: :code:`cutensornetContractionOptimizerConfigSetAttribute` --------------------------------------------------------- .. doxygenfunction:: cutensornetContractionOptimizerConfigSetAttribute ---- .. _cutensornetCreateContractionOptimizerInfo-label: :code:`cutensornetCreateContractionOptimizerInfo` ------------------------------------------------- .. doxygenfunction:: cutensornetCreateContractionOptimizerInfo ---- .. _cutensornetDestroyContractionOptimizerInfo-label: :code:`cutensornetDestroyContractionOptimizerInfo` -------------------------------------------------- .. doxygenfunction:: cutensornetDestroyContractionOptimizerInfo ---- .. _cutensornetContractionOptimize-label: :code:`cutensornetContractionOptimize` -------------------------------------- .. doxygenfunction:: cutensornetContractionOptimize ---- .. _cutensornetContractionOptimizerInfoGetAttribute-label: :code:`cutensornetContractionOptimizerInfoGetAttribute` ------------------------------------------------------- .. doxygenfunction:: cutensornetContractionOptimizerInfoGetAttribute ---- .. _cutensornetContractionOptimizerInfoSetAttribute-label: :code:`cutensornetContractionOptimizerInfoSetAttribute` ------------------------------------------------------- .. doxygenfunction:: cutensornetContractionOptimizerInfoSetAttribute ---- .. _cutensornetContractionOptimizerInfoGetPackedSize-label: :code:`cutensornetContractionOptimizerInfoGetPackedSize` -------------------------------------------------------- .. doxygenfunction:: cutensornetContractionOptimizerInfoGetPackedSize ---- .. _cutensornetContractionOptimizerInfoPackData-label: :code:`cutensornetContractionOptimizerInfoPackData` --------------------------------------------------- .. doxygenfunction:: cutensornetContractionOptimizerInfoPackData ---- .. _cutensornetCreateContractionOptimizerInfoFromPackedData-label: :code:`cutensornetCreateContractionOptimizerInfoFromPackedData` --------------------------------------------------------------- .. doxygenfunction:: cutensornetCreateContractionOptimizerInfoFromPackedData ---- .. _cutensornetUpdateContractionOptimizerInfoFromPackedData-label: :code:`cutensornetUpdateContractionOptimizerInfoFromPackedData` --------------------------------------------------------------- .. doxygenfunction:: cutensornetUpdateContractionOptimizerInfoFromPackedData ---- Contraction Plan API ==================== .. _cutensornetCreateContractionPlan-label: :code:`cutensornetCreateContractionPlan` ---------------------------------------- .. doxygenfunction:: cutensornetCreateContractionPlan ---- .. _cutensornetDestroyContractionPlan-label: :code:`cutensornetDestroyContractionPlan` ----------------------------------------- .. doxygenfunction:: cutensornetDestroyContractionPlan ---- .. _cutensornetContractionAutotune-label: :code:`cutensornetContractionAutotune` -------------------------------------- .. doxygenfunction:: cutensornetContractionAutotune ---- .. _cutensornetCreateContractionAutotunePreference-label: :code:`cutensornetCreateContractionAutotunePreference` ------------------------------------------------------ .. doxygenfunction:: cutensornetCreateContractionAutotunePreference ---- .. _cutensornetContractionAutotunePreferenceGetAttribute-label: :code:`cutensornetContractionAutotunePreferenceGetAttribute` ------------------------------------------------------------ .. doxygenfunction:: cutensornetContractionAutotunePreferenceGetAttribute ---- .. _cutensornetContractionAutotunePreferenceSetAttribute-label: :code:`cutensornetContractionAutotunePreferenceSetAttribute` ------------------------------------------------------------ .. doxygenfunction:: cutensornetContractionAutotunePreferenceSetAttribute ---- .. _cutensornetDestroyContractionAutotunePreference-label: :code:`cutensornetDestroyContractionAutotunePreference` ------------------------------------------------------- .. doxygenfunction:: cutensornetDestroyContractionAutotunePreference ---- .. _cuTensorNet workspace management API: Workspace Management API ======================== .. _cutensornetCreateWorkspaceDescriptor-label: :code:`cutensornetCreateWorkspaceDescriptor` -------------------------------------------- .. doxygenfunction:: cutensornetCreateWorkspaceDescriptor ---- .. _cutensornetWorkspaceComputeSizes-label: :code:`cutensornetWorkspaceComputeSizes` ---------------------------------------- .. doxygenfunction:: cutensornetWorkspaceComputeSizes ---- .. _cutensornetWorkspaceComputeContractionSizes-label: :code:`cutensornetWorkspaceComputeContractionSizes` --------------------------------------------------- .. doxygenfunction:: cutensornetWorkspaceComputeContractionSizes ---- .. _cutensornetWorkspaceComputeQRSizes-label: :code:`cutensornetWorkspaceComputeQRSizes` ------------------------------------------- .. doxygenfunction:: cutensornetWorkspaceComputeQRSizes ---- .. _cutensornetWorkspaceComputeSVDSizes-label: :code:`cutensornetWorkspaceComputeSVDSizes` ------------------------------------------- .. doxygenfunction:: cutensornetWorkspaceComputeSVDSizes ---- .. _cutensornetWorkspaceComputeGateSplitSizes-label: :code:`cutensornetWorkspaceComputeGateSplitSizes` ------------------------------------------------- .. doxygenfunction:: cutensornetWorkspaceComputeGateSplitSizes ---- .. _cutensornetWorkspaceGetSize-label: :code:`cutensornetWorkspaceGetSize` ----------------------------------- .. doxygenfunction:: cutensornetWorkspaceGetSize ---- .. _cutensornetWorkspaceGetMemorySize-label: :code:`cutensornetWorkspaceGetMemorySize` ----------------------------------------- .. doxygenfunction:: cutensornetWorkspaceGetMemorySize ---- .. _cutensornetWorkspaceSet-label: :code:`cutensornetWorkspaceSet` ------------------------------- .. doxygenfunction:: cutensornetWorkspaceSet ---- .. _cutensornetWorkspaceSetMemory-label: :code:`cutensornetWorkspaceSetMemory` ------------------------------------- .. doxygenfunction:: cutensornetWorkspaceSetMemory ---- .. _cutensornetWorkspaceGet-label: :code:`cutensornetWorkspaceGet` ------------------------------- .. doxygenfunction:: cutensornetWorkspaceGet ---- .. _cutensornetWorkspaceGetMemory-label: :code:`cutensornetWorkspaceGetMemory` ------------------------------------- .. doxygenfunction:: cutensornetWorkspaceGetMemory ---- .. _cutensornetWorkspacePurgeCache-label: :code:`cutensornetWorkspacePurgeCache` -------------------------------------- .. doxygenfunction:: cutensornetWorkspacePurgeCache ---- .. _cutensornetDestroyWorkspaceDescriptor-label: :code:`cutensornetDestroyWorkspaceDescriptor` --------------------------------------------- .. doxygenfunction:: cutensornetDestroyWorkspaceDescriptor ---- Network Contraction API ======================= .. _cutensornetContraction-label: :code:`cutensornetContraction` ------------------------------ .. doxygenfunction:: cutensornetContraction ---- .. _cutensornetContractSlices-label: :code:`cutensornetContractSlices` --------------------------------- .. doxygenfunction:: cutensornetContractSlices ---- Gradient Computation API ======================== .. _cutensornetComputeGradientsBackward-label: :code:`cutensornetComputeGradientsBackward` ------------------------------------------- .. doxygenfunction:: cutensornetComputeGradientsBackward ---- Slice Group API =============== .. _cutensornetCreateSliceGroupFromIDRange-label: :code:`cutensornetCreateSliceGroupFromIDRange` ---------------------------------------------- .. doxygenfunction:: cutensornetCreateSliceGroupFromIDRange ---- .. _cutensornetCreateSliceGroupFromIDs-label: :code:`cutensornetCreateSliceGroupFromIDs` ------------------------------------------ .. doxygenfunction:: cutensornetCreateSliceGroupFromIDs ---- .. _cutensornetDestroySliceGroup-label: :code:`cutensornetDestroySliceGroup` ------------------------------------ .. doxygenfunction:: cutensornetDestroySliceGroup ---- Approximate Tensor Network Execution API ======================================== .. _cutensornetTensorQR-label: :code:`cutensornetTensorQR` --------------------------- .. doxygenfunction:: cutensornetTensorQR ---- .. _cutensornetTensorSVD-label: :code:`cutensornetTensorSVD` ---------------------------- .. doxygenfunction:: cutensornetTensorSVD ---- .. _cutensornetGateSplit-label: :code:`cutensornetGateSplit` ---------------------------- .. doxygenfunction:: cutensornetGateSplit ---- Tensor SVD Config API ===================== .. _cutensornetCreateTensorSVDConfig-label: :code:`cutensornetCreateTensorSVDConfig` ---------------------------------------- .. doxygenfunction:: cutensornetCreateTensorSVDConfig ---- .. _cutensornetDestroyTensorSVDConfig-label: :code:`cutensornetDestroyTensorSVDConfig` ----------------------------------------- .. doxygenfunction:: cutensornetDestroyTensorSVDConfig ---- .. _cutensornetTensorSVDConfigGetAttribute-label: :code:`cutensornetTensorSVDConfigGetAttribute` ---------------------------------------------- .. doxygenfunction:: cutensornetTensorSVDConfigGetAttribute ---- .. _cutensornetTensorSVDConfigSetAttribute-label: :code:`cutensornetTensorSVDConfigSetAttribute` ---------------------------------------------- .. doxygenfunction:: cutensornetTensorSVDConfigSetAttribute ---- Tensor SVD Info API =================== .. _cutensornetCreateTensorSVDInfo-label: :code:`cutensornetCreateTensorSVDInfo` ---------------------------------------- .. doxygenfunction:: cutensornetCreateTensorSVDInfo ---- .. _cutensornetDestroyTensorSVDInfo-label: :code:`cutensornetDestroyTensorSVDInfo` ---------------------------------------- .. doxygenfunction:: cutensornetDestroyTensorSVDInfo ---- .. _cutensornetTensorSVDInfoGetAttribute-label: :code:`cutensornetTensorSVDInfoGetAttribute` -------------------------------------------- .. doxygenfunction:: cutensornetTensorSVDInfoGetAttribute ---- .. _cuTensorNet distributed parallelization API: Distributed Parallelization API =============================== .. _cutensornetDistributedResetConfiguration-label: :code:`cutensornetDistributedResetConfiguration` ------------------------------------------------ .. doxygenfunction:: cutensornetDistributedResetConfiguration ---- .. _cutensornetDistributedGetNumRanks-label: :code:`cutensornetDistributedGetNumRanks` ----------------------------------------- .. doxygenfunction:: cutensornetDistributedGetNumRanks ---- .. _cutensornetDistributedGetProcRank-label: :code:`cutensornetDistributedGetProcRank` ----------------------------------------- .. doxygenfunction:: cutensornetDistributedGetProcRank ---- .. _cutensornetDistributedSynchronize-label: :code:`cutensornetDistributedSynchronize` ----------------------------------------- .. doxygenfunction:: cutensornetDistributedSynchronize ---- .. _cuTensorNet High-Level API: High-Level Tensor Network API ============================= The high-level tensor network API functions centered around `cutensornetState_t` allow users to define complex tensor network states by gradually applying tensor operators (e.g., quantum gates) to the initial (vacuum) state residing in the user-defined direct-product space, that is, a tensor space constructed as a direct product of multiple vector spaces of given dimensions. In particular, this way of defining a tensor network state is very convenient for quantum circuit simulators since the final output state of a given quantum circuit is constructed by gradually applying quantum gates to the initial (vacuum) state of all qubits (or qudits). Once the action of all tensor operators has been specified, the underlying tensor network is completely defined, together with the final state of the tensor network that resides in the same direct-product space as the initial (vacuum) state. Users also have the following options to request certain approximations or actions applied to the final state before computing its various properties: * No additional approximations or actions. No additional API calls are required and users may directly proceed to the next steps for property computation. All properties will be computed by direct contraction of the full tensor network(s) corresponding to the property of interest. * Explicitly precompute the full state tensor. This can be achieved via a sequence of calls to `cutensornetStateConfigure`, `cutensornetStatePrepare`, and `cutensornetStateCompute` to configure, prepare and, finally, compute the full state tensor. The calculation of all subsequent properties may leverage the computed full state tensor (it is not guaranteed to do so). * Provide the initial quantum state to be a non-vacuum state in the Matrix Product State (MPS) form. This can be achieved by calling the `cutensornetStateInitializeMPS` API to provide the initial state before subsequent calls to the configure, prepare and compute API functions. Note that this API does not specify that the final state is to be computed in MPS (see below) and therefore can be used in conjunction with either contraction-based computation or MPS-based representation. * Factorize the final state in the MPS form. The `cutensornetStateFinalizeMPS` API function can be used to specify the MPS factorization structure for the defined tensor network state. Once the desired MPS factorization has been specified, subsequent calls to the configure, prepare, and compute API functions will configure the MPS computation, prepare the MPS computation, and, finally, compute the MPS factorization. All subsequent properties will be computed by using the MPS-factorized form of the original tensor network state. After choosing one of the approaches above, users can take advantage of the following APIs to compute various properties associated with the tensor network state: * `cutensornetStateAccessor_t` and corresponding APIs can be used to compute the full state tensor, any of its cartesian slices, or individual amplitudes. * `cutensornetStateExpectation_t` and corresponding APIs can be used to compute an expectation value of a given tensor network operator with respect to the given tensor network state. A tensor network operator (`cutensornetNetworkOperator_t`) is defined as a sum of products of tensor operators where tensors constituting each product (component) act on disjoint degrees of freedom (e.g., disjoint subsets of qudits). * `cutensornetStateMarginal_t` and corresponding APIs can be used to compute the marginal probability distribution tensors (reduced density matrices) over the specified modes of the tensor network state. In particular, including all tensor network state modes would result in the computation of the full density matrix of the tensor network state. * `cutensornetStateSampler_t` and corresponding APIs can be used to sample from the probability distribution associated with the specified tensor network state modes. .. _Figure 1_highlevelapi: .. figure:: ../../figures/cutn_high_level_api_workflow.png :width: 2294px :align: center Figure 1. cuTensorNet high-level API workflow logic. Arrows indicate allowed sequences of API calls. For each such property of the tensor network state that one may want to compute, the corresponding subset of the high-level API includes API functions for defining (creating) the feature-providing object (Create), like those named above, configuring it by setting specific attributes (Configure), preparing it for computation (Prepare), and, finally, computing it (Compute), and, of course, destroying it at the end (Destroy). See :ref:`Figure 1
` for the API workflow logic, where arrows indicate allowed sequences of API calls. .. note:: When the properties are to be computed for an MPS-factorized form of the tensor network state, users are responsible for explictly allocating memory for the MPS state tensor(s) and maintaining it for the lifetime of the `cutensornetState_t` object. For more detailed descriptions of MPS-based property computations, please refer to these sections on :doc:`amplitudes <../examples/mps-amplitudes>`, :doc:`expectation value <../examples/mps-expectation>`, :doc:`marginal distribution <../examples/mps-marginal>` and :doc:`sampling <../examples/mps-sampling>`. .. _cutensornetCreateState-label: :code:`cutensornetCreateState` ------------------------------ .. doxygenfunction:: cutensornetCreateState ---- .. _cutensornetDestroyState-label: :code:`cutensornetDestroyState` ------------------------------- .. doxygenfunction:: cutensornetDestroyState ---- .. _cutensornetStateApplyTensor-label: :code:`cutensornetStateApplyTensor` ----------------------------------- .. doxygenfunction:: cutensornetStateApplyTensor ---- .. _cutensornetStateApplyTensorOperator-label: :code:`cutensornetStateApplyTensorOperator` ------------------------------------------- .. doxygenfunction:: cutensornetStateApplyTensorOperator ---- .. _cutensornetStateApplyControlledTensorOperator-label: :code:`cutensornetStateApplyControlledTensorOperator` ----------------------------------------------------- .. doxygenfunction:: cutensornetStateApplyControlledTensorOperator ---- .. _cutensornetStateApplyUnitaryChannel-label: :code:`cutensornetStateApplyUnitaryChannel` ------------------------------------------- .. doxygenfunction:: cutensornetStateApplyUnitaryChannel ---- .. _cutensornetStateApplyNetworkOperator-label: :code:`cutensornetStateApplyNetworkOperator` -------------------------------------------- .. doxygenfunction:: cutensornetStateApplyNetworkOperator ---- .. _cutensornetStateUpdateTensor-label: :code:`cutensornetStateUpdateTensor` ------------------------------------ .. doxygenfunction:: cutensornetStateUpdateTensor ---- .. _cutensornetStateUpdateTensorOperator-label: :code:`cutensornetStateUpdateTensorOperator` -------------------------------------------- .. doxygenfunction:: cutensornetStateUpdateTensorOperator ---- .. _cutensornetStateConfigure-label: :code:`cutensornetStateConfigure` --------------------------------- .. doxygenfunction:: cutensornetStateConfigure ---- .. _cutensornetStatePrepare-label: :code:`cutensornetStatePrepare` ------------------------------- .. doxygenfunction:: cutensornetStatePrepare ---- .. _cutensornetStateGetInfo-label: :code:`cutensornetStateGetInfo` ------------------------------- .. doxygenfunction:: cutensornetStateGetInfo ---- .. _cutensornetStateCompute-label: :code:`cutensornetStateCompute` ------------------------------- .. doxygenfunction:: cutensornetStateCompute ---- .. _cutensornetGetOutputStateDetails-label: :code:`cutensornetGetOutputStateDetails` ---------------------------------------- .. doxygenfunction:: cutensornetGetOutputStateDetails ---- .. _cutensornetStateInitializeMPS-label: :code:`cutensornetStateInitializeMPS` ------------------------------------- .. doxygenfunction:: cutensornetStateInitializeMPS ---- .. _cutensornetStateFinalizeMPS-label: :code:`cutensornetStateFinalizeMPS` ----------------------------------- .. doxygenfunction:: cutensornetStateFinalizeMPS ---- .. _cutensornetStateCaptureMPS-label: :code:`cutensornetStateCaptureMPS` ---------------------------------- .. doxygenfunction:: cutensornetStateCaptureMPS ---- .. _cutensornetCreateNetworkOperator-label: :code:`cutensornetCreateNetworkOperator` ---------------------------------------- .. doxygenfunction:: cutensornetCreateNetworkOperator ---- .. _cutensornetNetworkOperatorAppendProduct-label: :code:`cutensornetNetworkOperatorAppendProduct` ----------------------------------------------- .. doxygenfunction:: cutensornetNetworkOperatorAppendProduct ---- .. _cutensornetNetworkOperatorAppendMPO-label: :code:`cutensornetNetworkOperatorAppendMPO` ------------------------------------------- .. doxygenfunction:: cutensornetNetworkOperatorAppendMPO ---- .. _cutensornetDestroyNetworkOperator-label: :code:`cutensornetDestroyNetworkOperator` ----------------------------------------- .. doxygenfunction:: cutensornetDestroyNetworkOperator ---- .. _cutensornetCreateAccessor-label: :code:`cutensornetCreateAccessor` --------------------------------- .. doxygenfunction:: cutensornetCreateAccessor ---- .. _cutensornetDestroyAccessor-label: :code:`cutensornetDestroyAccessor` ---------------------------------- .. doxygenfunction:: cutensornetDestroyAccessor ---- .. _cutensornetAccessorConfigure-label: :code:`cutensornetAccessorConfigure` ------------------------------------ .. doxygenfunction:: cutensornetAccessorConfigure ---- .. _cutensornetAccessorPrepare-label: :code:`cutensornetAccessorPrepare` ---------------------------------- .. doxygenfunction:: cutensornetAccessorPrepare ---- .. _cutensornetAccessorGetInfo-label: :code:`cutensornetAccessorGetInfo` ---------------------------------- .. doxygenfunction:: cutensornetAccessorGetInfo ---- .. _cutensornetAccessorCompute-label: :code:`cutensornetAccessorCompute` ---------------------------------- .. doxygenfunction:: cutensornetAccessorCompute ---- .. _cutensornetCreateExpectation-label: :code:`cutensornetCreateExpectation` ------------------------------------ .. doxygenfunction:: cutensornetCreateExpectation ---- .. _cutensornetDestroyExpectation-label: :code:`cutensornetDestroyExpectation` ------------------------------------- .. doxygenfunction:: cutensornetDestroyExpectation ---- .. _cutensornetExpectationConfigure-label: :code:`cutensornetExpectationConfigure` --------------------------------------- .. doxygenfunction:: cutensornetExpectationConfigure ---- .. _cutensornetExpectationPrepare-label: :code:`cutensornetExpectationPrepare` ------------------------------------- .. doxygenfunction:: cutensornetExpectationPrepare ---- .. _cutensornetExpectationGetInfo-label: :code:`cutensornetExpectationGetInfo` ------------------------------------- .. doxygenfunction:: cutensornetExpectationGetInfo ---- .. _cutensornetExpectationCompute-label: :code:`cutensornetExpectationCompute` ------------------------------------- .. doxygenfunction:: cutensornetExpectationCompute ---- .. _cutensornetCreateMarginal-label: :code:`cutensornetCreateMarginal` --------------------------------- .. doxygenfunction:: cutensornetCreateMarginal ---- .. _cutensornetDestroyMarginal-label: :code:`cutensornetDestroyMarginal` ---------------------------------- .. doxygenfunction:: cutensornetDestroyMarginal ---- .. _cutensornetMarginalConfigure-label: :code:`cutensornetMarginalConfigure` ------------------------------------ .. doxygenfunction:: cutensornetMarginalConfigure ---- .. _cutensornetMarginalPrepare-label: :code:`cutensornetMarginalPrepare` ---------------------------------- .. doxygenfunction:: cutensornetMarginalPrepare ---- .. _cutensornetMarginalGetInfo-label: :code:`cutensornetMarginalGetInfo` ---------------------------------- .. doxygenfunction:: cutensornetMarginalGetInfo ---- .. _cutensornetMarginalCompute-label: :code:`cutensornetMarginalCompute` ---------------------------------- .. doxygenfunction:: cutensornetMarginalCompute ---- .. _cutensornetCreateSampler-label: :code:`cutensornetCreateSampler` -------------------------------- .. doxygenfunction:: cutensornetCreateSampler ---- .. _cutensornetDestroySampler-label: :code:`cutensornetDestroySampler` --------------------------------- .. doxygenfunction:: cutensornetDestroySampler ---- .. _cutensornetSamplerConfigure-label: :code:`cutensornetSamplerConfigure` ----------------------------------- .. doxygenfunction:: cutensornetSamplerConfigure ---- .. _cutensornetSamplerPrepare-label: :code:`cutensornetSamplerPrepare` --------------------------------- .. doxygenfunction:: cutensornetSamplerPrepare ---- .. _cutensornetSamplerGetInfo-label: :code:`cutensornetSamplerGetInfo` --------------------------------- .. doxygenfunction:: cutensornetSamplerGetInfo ---- .. _cutensornetSamplerSample-label: :code:`cutensornetSamplerSample` -------------------------------- .. doxygenfunction:: cutensornetSamplerSample ---- .. _cuTensorNet memory management API: Memory Management API ===================== A *stream-ordered* memory allocator (or mempool for short) allocates/deallocates memory *asynchronously* from/to a mempool in a stream-ordered fashion, meaning memory operations and computations enqueued on the streams have a well-defined inter- and intra- stream dependency. There are several well-implemented stream-ordered mempools available, such as ``cudaMemPool_t`` that is built-in at the CUDA driver level since CUDA 11.2 (so that all CUDA applications in the same process can easily share the same pool, see `here `_) and the RAPIDS Memory Manager (`RMM`_). For a detailed introduction, see the `NVIDIA Developer Blog`_. .. _RMM: https://github.com/rapidsai/rmm .. _NVIDIA Developer Blog: https://developer.nvidia.com/blog/using-cuda-stream-ordered-memory-allocator-part-1/ The new device memory handler APIs allow users to bind a stream-ordered mempool to the library handle, such that cuTensorNet can take care of most of the memory management for users. Below is an illustration of what can be done: .. code-block:: c++ MyMemPool pool = MyMemPool(); // kept alive for the entire process in real apps int my_alloc(void* ctx, void** ptr, size_t size, cudaStream_t stream) { // assuming this is the memory allocation routine provided by my mempool return reinterpret_cast(ctx)->alloc(ptr, size, stream); } int my_dealloc(void* ctx, void* ptr, size_t size, cudaStream_t stream) { // assuming this is the memory deallocation routine provided by my mempool return reinterpret_cast(ctx)->dealloc(ptr, size, stream); } // create a mem handler and fill in the required members for the library to use cutensornetDeviceMemHandler_t handler; handler.ctx = reinterpret_cast(&pool); handler.device_alloc = my_alloc; handler.device_free = my_dealloc; memcpy(handler.name, std::string("my pool").c_str(), CUTENSORNET_ALLOCATOR_NAME_LEN); // bind the handler to the library handle cutensornetSetDeviceMemHandler(handle, &handler); /* ... perform the network creation & optimization as usual ... */ // create a workspace descriptor cutensornetWorkspaceDescriptor_t workDesc; // (this step is optional and workDesc can be set to NULL if one just wants // to use the "recommended" workspace size) cutensornetCreateWorkspaceDescriptor(handle, &workDesc); // User doesn’t compute the required sizes // User doesn’t query the workspace size (but one can if desired) // User doesn’t allocate memory! // User sets workspacePtr=NULL for the corresponding memory space (device, in this case) to indicate the library should // draw memory (of the "recommended" size, if the workspace size is set to 0 as shown below) from the user's pool; // if a nonzero size is set, we would use the given size instead of the recommended one. // (this step is also optional if workDesc has been set to NULL) cutensornetWorkspaceSetMemory(handle, workDesc, CUTENSORNET_MEMSPACE_DEVICE, CUTENSORNET_WORKSPACE_SCRATCH, NULL, 0); // create a contraction plan cutensornetContractionPlan_t plan; cutensornetCreateContractionPlan(handle, descNet, optimizerInfo, workDesc, &plan); // autotune the plan with the workspace cutensornetContractionAutotune(handle, plan, rawDataIn, rawDataOut, workDesc, pref, stream); // perform actual contraction with the workspace for (int sliceId=0; sliceId