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 allow users to define complex tensor network states by gradually applying tensor operators to the initial (vacuum) state residing in the user-defined tensor-product space, that is, the space constructed as a tensor product of multiple vector spaces of given dimensions. Such a way of defining the tensor network states 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 have been specified, the underlying tensor network is completely defined, together with the final state of the tensor network that resides in the same tensor-product space as the initial (vacuum) state. At this point, different properties of the defined tensor network state can be computed. ``cutensornetStateMarginal_t`` and corresponding API 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 API can be used to sample from the probability distribution associated with the specified tensor network state modes. 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, like those named above, configuring it by setting specific attributes, preparing it for computation, and, finally, computing it (and, of course, destroying it at the end). .. _cutensornetCreateState-label: :code:`cutensornetCreateState` ------------------------------ .. doxygenfunction:: cutensornetCreateState ---- .. _cutensornetDestroyState-label: :code:`cutensornetDestroyState` ------------------------------- .. doxygenfunction:: cutensornetDestroyState ---- .. _cutensornetStateApplyTensor-label: :code:`cutensornetStateApplyTensor` ----------------------------------- .. doxygenfunction:: cutensornetStateApplyTensor ---- .. _cutensornetStateUpdateTensor-label: :code:`cutensornetStateUpdateTensor` ------------------------------------ .. doxygenfunction:: cutensornetStateUpdateTensor ---- .. _cutensornetCreateMarginal-label: :code:`cutensornetCreateMarginal` --------------------------------- .. doxygenfunction:: cutensornetCreateMarginal ---- .. _cutensornetDestroyMarginal-label: :code:`cutensornetDestroyMarginal` ---------------------------------- .. doxygenfunction:: cutensornetDestroyMarginal ---- .. _cutensornetMarginalConfigure-label: :code:`cutensornetMarginalConfigure` ------------------------------------ .. doxygenfunction:: cutensornetMarginalConfigure ---- .. _cutensornetMarginalPrepare-label: :code:`cutensornetMarginalPrepare` ---------------------------------- .. doxygenfunction:: cutensornetMarginalPrepare ---- .. _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 ---- .. _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