pygsti.optimize.arraysinterface.DistributedArraysInterface

pygsti.optimize.arraysinterface.DistributedArraysInterface#

class DistributedArraysInterface(dist_layout, lsvec_mode, extra_elements=0)#

Bases: ArraysInterface

An arrays interface where the arrays are distributed according to a distributed layout.

Parameters:

  • dist_layout (DistributableCOPALayout) – The layout giving the distribution of the arrays.

  • extra_elements (int, optional) – The number of additional objective function “elements” beyond those specified by dist_layout. These are often used for penalty terms.

Methods

__init__(dist_layout, lsvec_mode[, ...])

allgather_f(f, global_f)

Gather an objective function (f) vector onto all the processors.

allgather_x(x, global_x)

Gather a parameter (x) vector onto all the processors.

allocate_jac()

Allocate an array for holding a Jacobian matrix (type 'ep').

allocate_jtf()

Allocate an array for holding a 'jtf'-type value.

allocate_jtj()

Allocate an array for holding an approximated Hessian (type 'jtj').

allocate_jtj_shared_mem_buf()

Allocate scratch space to be used for repeated calls to fill_jtj().

allscatter_x(global_x, x)

Pare down an already-scattered global parameter (x) vector to be just a local x vector.

deallocate_jac(jac)

Free an array for holding a Jacobian matrix (type 'ep').

deallocate_jtf(jtf)

Free an array for holding an objective function value (type 'jtf').

deallocate_jtj(jtj)

Free an array for holding an approximated Hessian (type 'jtj').

deallocate_jtj_shared_mem_buf(jtj_buf)

Frees the scratch memory allocated by allocate_jtj_shared_mem_buf().

dot_x(x1, x2)

Take the dot product of two x-type vectors.

fill_dx_svd(jac_v, global_vec, dx)

Computes the dot product of a jtj-type array with a global parameter array.

fill_jtf(j, f, jtf)

Compute dot(Jacobian.T, f) in supplied memory.

fill_jtj(j, jtj[, shared_mem_buf])

Compute dot(Jacobian.T, Jacobian) in supplied memory.

gather_jtf(jtf[, return_shared])

Gather a jtf vector onto the root processor.

gather_jtj(jtj[, return_shared])

Gather a Hessian (jtj) matrix onto the root processor.

global_num_elements()

The total number of objective function "elements".

global_svd_dot(jac_v, minus_jtf)

Gathers the dot product between a jtj-type matrix and a jtf-type vector into a global result array.

infnorm_x(x)

Compute the infinity-norm of an x-type vector.

jac_param_slice([only_if_leader])

The slice into a Jacobian's columns that belong to this processor.

jtf_param_slice()

The slice into a 'jtf' vector giving the rows of owned by this processor.

jtj_diag_indices(jtj)

The indices into a jtj-type array that correspond to diagonal elements of the global matrix.

jtj_max_diagonal_element(jtj)

jtj_pre_regularization_data(jtj)

jtj_update_regularization(jtj, prd, mu)

max_x(x)

Compute the maximum of an x-type vector.

min_x(x)

Compute the minimum of an x-type vector.

norm2_f(f)

Compute the Frobenius norm squared of an f-type vector.

norm2_jac(j)

Compute the Frobenius norm squared of an Jacobian matrix (ep-type).

norm2_jtj(jtj)

Compute the Frobenius norm squared of an jtj-type matrix.

norm2_x(x)

Compute the Frobenius norm squared of an x-type vector.

param_fine_info()

Returns information regarding how model parameters are distributed among hosts and processors.

scatter_jtf(global_jtf, jtf)

Scatter a jtf vector onto all the processors.

scatter_jtj(global_jtj, jtj)

Scatter a Hessian (jtj) matrix onto all the processors.

scatter_x(global_x, x)

Scatter a global parameter (x) vector onto all the processors.
allgather_f(f, global_f)#

Gather an objective function (f) vector onto all the processors.

Parameters:
Return type:

None

allgather_x(x, global_x)#

Gather a parameter (x) vector onto all the processors.

Parameters:
Return type:

None

allocate_jac()#

Allocate an array for holding a Jacobian matrix (type ‘ep’).

Note: this function is only called when the Jacobian needs to be approximated with finite differences.

Return type:

numpy.ndarray or LocalNumpyArray

allocate_jtf()#

Allocate an array for holding a ‘jtf’-type value.

Return type:

numpy.ndarray or LocalNumpyArray

allocate_jtj()#

Allocate an array for holding an approximated Hessian (type ‘jtj’).

Return type:

numpy.ndarray or LocalNumpyArray

allocate_jtj_shared_mem_buf()#

Allocate scratch space to be used for repeated calls to fill_jtj().

Returns:

  • scratch (numpy.ndarray or None) – The scratch array.

  • shared_memory_handle (multiprocessing.shared_memory.SharedMemory or None) – The shared memory handle associated with scratch, which is needed to free the memory.

allscatter_x(global_x, x)#

Pare down an already-scattered global parameter (x) vector to be just a local x vector.

Parameters:

  • global_x (numpy.array or LocalNumpyArray) – The input vector. This global vector is already present on all the processors, so there’s no need to do any MPI communication.

  • x (numpy.array or LocalNumpyArray) – The output vector, typically a slice of global_x.

Return type:

None

deallocate_jac(jac)#

Free an array for holding a Jacobian matrix (type ‘ep’).

Return type:

None

deallocate_jtf(jtf)#

Free an array for holding an objective function value (type ‘jtf’).

Return type:

None

deallocate_jtj(jtj)#

Free an array for holding an approximated Hessian (type ‘jtj’).

Return type:

None

deallocate_jtj_shared_mem_buf(jtj_buf)#

Frees the scratch memory allocated by allocate_jtj_shared_mem_buf().

Parameters:

jtj_buf (tuple or None) – The value returned from allocate_jtj_shared_mem_buf()

dot_x(x1, x2)#

Take the dot product of two x-type vectors.

Parameters:
Return type:

float

fill_dx_svd(jac_v, global_vec, dx)#

Computes the dot product of a jtj-type array with a global parameter array.

The result (dx) is a jtf-type array. This is typically used for computing the x-update vector in the LM method when using a SVD-defined basis.

Parameters:

  • jac_v (numpy.ndarray or LocalNumpyArray) – An array of jtj-type.

  • global_vec (numpy.ndarray) – A global parameter vector.

  • dx (numpy.ndarray or LocalNumpyArray) – An array of jtf-type. Filled with dot(jac_v, global_vec) values.

Return type:

None

fill_jtf(j, f, jtf)#

Compute dot(Jacobian.T, f) in supplied memory.

Parameters:

  • j (numpy.ndarray or LocalNumpyArray) – Jacobian matrix (type ep).

  • f (numpy.ndarray or LocalNumpyArray) – Objective function vector (type e).

  • jtf (numpy.ndarray or LocalNumpyArray) – Output array, type jtf. Filled with dot(j.T, f) values.

Return type:

None

fill_jtj(j, jtj, shared_mem_buf=None)#

Compute dot(Jacobian.T, Jacobian) in supplied memory.

Parameters:

  • j (numpy.ndarray or LocalNumpyArray) – Jacobian matrix (type ep).

  • jtf (numpy.ndarray or LocalNumpyArray) – Output array, type jtj. Filled with dot(j.T, j) values.

  • shared_mem_buf (tuple or None) – Scratch space of shared memory used to speed up repeated calls to fill_jtj. If not none, the value returned from allocate_jtj_shared_mem_buf().

Return type:

None

gather_jtf(jtf, return_shared=False)#

Gather a jtf vector onto the root processor.

Parameters:

  • jtf (numpy.array or LocalNumpyArray) – The local input vector to gather.

  • return_shared (bool, optional) – Whether the returned array is allowed to be a shared-memory array, which results in a small performance gain because the array used internally to gather the results can be returned directly. When True a shared memory handle is also returned, and the caller assumes responsibility for freeing the memory via pygsti.tools.sharedmemtools.cleanup_shared_ndarray().

Returns:

  • gathered_array (numpy.ndarray or None) – The full (global) output array on the root (rank=0) processor and None on all other processors.

  • shared_memory_handle (multiprocessing.shared_memory.SharedMemory or None) – Returned only when return_shared == True. The shared memory handle associated with gathered_array, which is needed to free the memory.

gather_jtj(jtj, return_shared=False)#

Gather a Hessian (jtj) matrix onto the root processor.

Parameters:

  • jtj (numpy.array or LocalNumpyArray) – The (local) input matrix to gather.

  • return_shared (bool, optional) – Whether the returned array is allowed to be a shared-memory array, which results in a small performance gain because the array used internally to gather the results can be returned directly. When True a shared memory handle is also returned, and the caller assumes responsibility for freeing the memory via pygsti.tools.sharedmemtools.cleanup_shared_ndarray().

Returns:

  • gathered_array (numpy.ndarray or None) – The full (global) output array on the root (rank=0) processor and None on all other processors.

  • shared_memory_handle (multiprocessing.shared_memory.SharedMemory or None) – Returned only when return_shared == True. The shared memory handle associated with gathered_array, which is needed to free the memory.

global_num_elements()#

The total number of objective function “elements”.

This is the size/length of the objective function f vector.

Return type:

int

global_svd_dot(jac_v, minus_jtf)#

Gathers the dot product between a jtj-type matrix and a jtf-type vector into a global result array.

This is typically used within SVD-defined basis calculations, where jac_v is the “V” matrix of the SVD of a jacobian, and minus_jtf is the negative dot product between the Jacobian matrix and objective function vector.

Parameters:
Returns:

The global (gathered) parameter vector dot(jac_v.T, minus_jtf).

Return type:

numpy.ndarray

infnorm_x(x)#

Compute the infinity-norm of an x-type vector.

Parameters:

x (numpy.ndarray or LocalNumpyArray) – The vector to operate on.

Return type:

float

jac_param_slice(only_if_leader=False)#

The slice into a Jacobian’s columns that belong to this processor.

Parameters:

only_if_leader (bool, optional) – If True, the current processor’s parameter slice is only returned if the processor is the “leader” (i.e. the first) of the processors that calculate the same parameter slice. All non-leader processors return the zero-slice slice(0,0).

Return type:

slice

jtf_param_slice()#

The slice into a ‘jtf’ vector giving the rows of owned by this processor.

Return type:

slice

jtj_diag_indices(jtj)#

The indices into a jtj-type array that correspond to diagonal elements of the global matrix.

If jtj were a global quantity, then this would just be numpy.diag_indices_from(jtj), however, it may be more complicated in actuality when different processors hold different sections of the global matrix.

Parameters:

jtj (numpy.ndarray or None) – The jtj-type array to get the indices with respect to.

Returns:

A tuple of 1D arrays that can be used to index the elements of jtj that correspond to diagonal elements of the global jtj matrix.

Return type:

tuple

max_x(x)#

Compute the maximum of an x-type vector.

Parameters:

x (numpy.ndarray or LocalNumpyArray) – The vector to operate on.

Return type:

float

min_x(x)#

Compute the minimum of an x-type vector.

Parameters:

x (numpy.ndarray or LocalNumpyArray) – The vector to operate on.

Return type:

float

norm2_f(f)#

Compute the Frobenius norm squared of an f-type vector.

Parameters:

f (numpy.ndarray or LocalNumpyArray) – The vector to operate on.

Return type:

float

norm2_jac(j)#

Compute the Frobenius norm squared of an Jacobian matrix (ep-type).

Parameters:

j (numpy.ndarray or LocalNumpyArray) – The Jacobian to operate on.

Return type:

float

norm2_jtj(jtj)#

Compute the Frobenius norm squared of an jtj-type matrix.

Parameters:

jtj (numpy.ndarray or LocalNumpyArray) – The array to operate on.

Return type:

float

norm2_x(x)#

Compute the Frobenius norm squared of an x-type vector.

Parameters:

x (numpy.ndarray or LocalNumpyArray) – The vector to operate on.

Return type:

float

param_fine_info()#

Returns information regarding how model parameters are distributed among hosts and processors.

This information relates to the “fine” distribution used in distributed layouts, and is needed by some algorithms which utilize shared-memory communication between processors on the same host.

Returns:

  • param_fine_slices_by_host (list) – A list with one entry per host. Each entry is itself a list of (rank, (global_param_slice, host_param_slice)) elements where rank is the top-level overall rank of a processor, global_param_slice is the parameter slice that processor owns and host_param_slice is the same slice relative to the parameters owned by the host.

  • owner_host_and_rank_of_global_fine_param_index (dict) – A mapping between parameter indices (keys) and the owning processor rank and host index. Values are (host_index, processor_rank) tuples.

scatter_jtf(global_jtf, jtf)#

Scatter a jtf vector onto all the processors.

Parameters:

  • global_jtf (numpy.ndarray) – The global vector to scatter.

  • jtf (numpy.ndarray or LocalNumpyArray) – The local destination array.

Return type:

None

scatter_jtj(global_jtj, jtj)#

Scatter a Hessian (jtj) matrix onto all the processors.

Parameters:

  • global_jtj (numpy.ndarray) – The global Hessian matrix to scatter.

  • jtj (numpy.ndarray or LocalNumpyArray) – The local destination array.

Return type:

None

scatter_x(global_x, x)#

Scatter a global parameter (x) vector onto all the processors.

Parameters:
Return type:

None