Unitary

The Unitary class is the base class for all unitary operators in QuOp_MPI. Custom propagators should inherit from this class.

Class Reference

class quop_mpi.Unitary(operator_function: Callable, operator_n_params: int = 0, operator_dict: dict | None = None, parameter_function: Callable | None = None, param_dict: dict | None = None, unitary_n_params: int = 1)

Bases: Bindable

Base class for a unitary.

A unitary is derived from the Unitary class and implements simulation of a specfic unitary through definition of the following methods:

propagate()
plan()
copy_plan()
destroy()

A list of unitary instances passed to quop_mpi.Ansatz.set_unitaries() defines the ansatz unitary of a QVA. After initialisation, unitary instances are managed by the quop_mpi.Ansatz class and calls to unitary methods are not made explicitly.

See quop_mpi.propagator for predefined unitary subclasses.

Associated QuOp Functions:

The following attributes are common to all unitary instances.

Attributes:

final_state: The system state after the action of the unitary.
initial_parameters: Initial variational parameters returned from the user-defined Parameter Function.
initial_state: The initial state of the quantum system.
n_params: The total number of unitary and operator parameterising the unitary.
operator_function: The user-defined Operator Function.
operator_dict: A FunctionDict of additional position and keyword arguments for the Operator Function.
operator: The operator object returned by the Operator Function.
operator_n_params: Number of variational operator parameters.
parameter_function: The user-defined Parameter Function.
param_dict: A FunctionDict of additional position and keyword arguments for the Parameter Function.
planner: If True, the parallel partitioning scheme returned by plan() takes precedence over non-planner unitaries and unitaries that appear later in the ansatz unitary list supplied to quop_mpi.Ansatz.set_unitaries().
seed: Integer for seeding random number generation, shared with quop_mpi.Ansatz.
system_size: The size of the simulated quantum system, shared with quop_mpi.Ansatz.
unitary_n_params: The number of unitary parameters.
unitary_type: A string labeling the unitary type (e.g. “diagonal” or “sparse”).
variational_parameters: Operator variational parameters. If present as an argument of the Operator Function, a real array of size operator_n_params is passed to the Operator Function.
MPI_COMM: MPI Intracommunicator, shared with quop_mpi.Ansatz.
alloc_local: The size of the array storing the :term`operator` if the operator is an array (equal to local_i otherwise). The second return value of plan().
lb: The lower global index of the local system state partition.
ub: The upper global index of the local system state partition.
local_i: The size of the local system state partition. The first return value of plan()
local_i_offset: The global index offset of the local system state partition.
partition_table: 1-D integer array describing the global partitioning scheme such that for a given MPI rank partition_table[rank + 1] - partition_table[rank] = local_i

comm_size_constraints: Constraints on valid MPI communicator sizes for this unitary. A list of 1-D integer arrays specifying divisibility requirements. Used by quop_mpi.Ansatz() to determine compatible parallelization.

copy_plan(ex_unitary: Unitary)

Perform any setup required by the propagation method called in propagate().

When implemented, copy_plan performs the same internal operations as plan() using the local_i and alloc_local attributes of ex_unitary. Does not return [local_i, alloc_local].

Warning

Not implemented by the base Unitary class.

Parameters:

ex_unitaryunitary: a unitary instance with computed local_i and alloc_local attributes

destroy()

Free memory allocated by Python extension modules in plan() or copy_plan(). collector.

Memory allocated by compiled Python extension modules is typically not managed by the Python garbage collector. These allocations must be freed via relevant methods in the extension module to prevent the occurrence of memory leaks.

Warning

Not implemented by the base Unitary class.

plan(system_size: int, MPI_COMM: mpi4py.MPI.Intracomm)

Plan the partitioning scheme used by an quop_mpi.Ansatz instance and performs any other tasks required by propagate().

An implemented plan returns (local_i, alloc_local). Data structures and allocation required by the propagation method called in propagate() are assigned to attributes of the Unitary instance.

The alloc_local return value specifies the size of the local system state arrays initial_state and final_state. In most cases alloc_local == local_i, however alloc_local > local_i may be required by particular external propagation methods (e.g. the parallel FFTW).

Warning

Not implemented by the base Unitary class.

Parameters:

system_sizeint: size of the simulated quantum system.
MPI_COMMIntracomm: MPI communicator over which the Ansatz observables, initial state and final state are partitioned.

Returns:

(int, int): number of elements in a row-wise partitioning of the system state and size to allocate for the initial_state and final_state arrays

Examples

def plan(self, system_size, MPI_COMM):

    local_i = system_size  // MPI_COMM.size

    local_i = (
        system_size - local_i * MPI_COMM.rank if MPI_COMM.rank == 0
        else local_i
    )

    alloc_local = local_i

    return local_i, alloc_local

propagate(x: np.ndarray[np.float64])

Simulation of the action of a :term`unitary`.

When implemented, propagate contains a call to a method (typically a contained in a complied Python extension module) that takes the class attributes initial_state, final_state and MPI_COMM, together with attributes describing the parallel partitioning scheme and variational parameters x, as input. The action of the unitary is computed in MPI parallel, with the computed result written to final_state.

Warning

Not implemented by the base Unitary class.

Parameters:

xndarray[float64]: a 1-D real array of n_params variational parameters

Examples

def propagate(self, x):

    external_propagator(
        x, self.partition_table, self.initial_state,
        self.final_state, self.MPI_COMM )