qwak_cupy package

Submodules

qwak_cupy.Errors module

exception Error(error_name, details)[source]

Bases: BaseException

Base class for custom exceptions in the application.

Attributes:

error_namestr

Name of the error.

detailsstr

Additional details about the error.

as_string()[source]

Return a string representation of the error message

Return type:

str

Returns:

String representation of the error message.

Return type:

str

Parameters:

  • error_name (str)

  • details (str)

exception StateOutOfBounds(details)[source]

Bases: Error

This exception is raised when the state is out of the expected bounds. Initialize the error instance with error name and details. Inherits from Error class.

Parameters:

details (str) – Additional details about the error.

Return type:

None

exception NonUnitaryState(details)[source]

Bases: Error

This exception is raised when the state is not unitary. Initialize the error instance with error name and details.

Parameters:

details (str) – Additional details about the error.

Return type:

None

exception UndefinedTimeList(details)[source]

Bases: Error

This exception is raised when the time interval for multiple walks is undefined. Initialize the error instance with error name and details.

Parameters:

details (str) – Additional details about the error.

Return type:

None

exception EmptyProbDistList(details)[source]

Bases: Error

This exception is raised when the probability distribution list is empty. Initialize the error instance with error name and details.

Parameters:

details (str) – Additional details about the error.

Return type:

None

exception MissingNodeInput(details)[source]

Bases: Error

This exception is raised when input nodes are required but not provided. Initialize the error instance with error name and details.

Parameters:

details (str) – Additional details about the error.

Return type:

None

exception MissingGraphInput(details)[source]

Bases: Error

This exception is raised when a graph is required but not provided.

Parameters:

details (str) – Additional details about the error.

qwak_cupy.Operator module

class Operator(graph, gamma=1, time=0, laplacian=False, markedElements=[])[source]

Bases: object

Class for the quantum walk operator.

This object is initialized with a user inputted graph, which is then used to generate the dimension of the operator and the adjacency matrix, which is the central structure required to perform walks on regular graphs. Note that this version of the software only supports regular undirected graphs, which will hopefully be generalized in the future.

The eigenvalues and eigenvectors of the adjacency matrix are also calculated during initialization, which are then used to calculate the diagonal operator through spectral decomposition. This was the chosen method since it is computationally cheaper than calculating the matrix exponent directly.

TODO: CheckPST is not defined here. Since it will probably be moved to the TODO: utils folder, it will be necessary to import it here.

Parameters:

  • graph (nx.Graph) – Graph where the walk will be performed.

  • gamma (float) – Needs Completion.

  • time (float, optional) – Time for which to calculate the operator, by default None.

  • laplacian (bool, optional) – Allows the user to choose whether to use the Laplacian or simple adjacency matrix, by default False.

  • markedElements (list, optional) – List with marked elements for search, by default None.

buildDiagonalOperator(time=0)[source]

Builds operator matrix from optional time and transition rate parameters, defined by user.

The first step is to calculate the diagonal matrix that takes in time, transition rate and eigenvalues and convert it to a list of the diagonal entries.

The entries are then multiplied by the eigenvectors, and the last step is to perform matrix multiplication with the complex conjugate of the eigenvectors.

Return type:

None

Parameters:

  • time (float, optional) – Time for which to calculate the operator, by default 0.

  • gamma (float, optional) – Needs completion.

  • round (int, optional)

buildExpmOperator(time=0)[source]

Builds operator matrix from optional time and transition rate parameters, defined by user.

Uses the scipy function expm to calculate the matrix exponential of the adjacency matrix.

Return type:

None

Parameters:

time (float, optional) – Time for which to calculate the operator, by default 0.

_buildHamiltonian(graph, laplacian)[source]

Builds the hamiltonian of the graph, which is either the Laplacian or the simple matrix.

Return type:

ndarray

Parameters:

  • laplacian (bool) – Allows the user to choose whether to use the Laplacian or simple adjacency matrix.

  • markedElements (list) – List of elements for the search.

_buildSearchHamiltonian(hamiltonian, markedElements)[source]
_buildEigenValues(hamiltonian)[source]

Builds the eigenvalues and eigenvectors of the adjacency matrix.

Return type:

None

Parameters:

isHermitian (bool) – Checks if the adjacency matrix is Hermitian.

_hermitianTest(hamiltonian)[source]

Checks if the adjacency matrix is Hermitian.

Return type:

bool

Parameters:

hamiltonian (cp.ndarray) – Adjacency matrix.

Returns:

True if Hermitian, False otherwise.

Return type:

bool

getEigenValues()[source]

Returns the eigenvalues of the adjacency matrix.

Return type:

list

Returns:

List of eigenvalues.

Return type:

list

_setEigenValues(eigenValues)[source]

Sets the eigenvalues of the adjacency matrix.

Return type:

None

Parameters:

eigenValues (list) – List of eigenvalues.

getEigenVectors()[source]

Returns the eigenvectors of the adjacency matrix.

Return type:

list

Returns:

List of eigenvectors.

Return type:

list

_setEigenVectors(eigenVectors)[source]

Sets the eigenvectors of the adjacency matrix.

Return type:

None

Parameters:

eigenVectors (list) – _description_

getHamiltonian()[source]

Returns the hamiltonian of the graph, which is either the Laplacian or the simple matrix.

Returns:

Hamiltonian of the graph.

Return type:

cp.ndarray

setHamiltonian(hamiltonian)[source]

Sets the hamiltonian for the walk.

Parameters:

hamiltonian (cp.ndarray) – Hamiltonian of the graph.

resetOperator()[source]

Resets Operator object.

Return type:

None

setDim(newDim, graph)[source]

Sets the current Operator objects dimension to a user defined one.

Return type:

None

Parameters:

  • newDim (int) – New dimension for the Operator object.

  • graph (nx.Graph) – New graph for the Operator object.

getDim()[source]

Gets the current graph dimension.

Return type:

int

Returns:

Dimension of Operator object.

Return type:

int

setTime(newTime)[source]

Sets the current operator time to a user defined one.

Return type:

None

Parameters:

newTime (float) – New operator time.

getTime()[source]

Gets the current operator time.

Return type:

float

Returns:

Current time of Operator object.

Return type:

float

setAdjacencyMatrix(adjacencyMatrix)[source]

Sets the adjacency matrix of the operator to a user defined one. Might make more sense to not give the user control over this parameter, and make them instead change the graph entirely.

Return type:

None

Parameters:

adjacencyMatrix (cp.ndarray) – New adjacency matrix for the Operator object.

_setAdjacencyMatrixOnly(adjacencyMatrix)[source]

Sets the adjacency matrix of the operator to a user defined one. Might make more sense to not give the user control over this parameter, and make them instead change the graph entirely.

Return type:

None

Parameters:

adjacencyMatrix (cp.ndarray) – New adjacency matrix.

getAdjacencyMatrix()[source]

Gets the current adjacency matrix of the Operator.

Return type:

ndarray

Returns:

Adjacency matrix of the Operator.

Return type:

cp.ndarray

_setOperatorVec(newOperator)[source]

Sets all the parameters of the current operator to user defined ones.

Return type:

None

Parameters:

newOperator (Operator) – New user inputted Operator.

setOperator(newOperator)[source]

Sets all the parameters of the current operator to user defined ones.

Return type:

None

Parameters:

newOperator (Operator) – New user inputted Operator.

getOperator()[source]

Gets the cupy ndarray associated with the current operator.

Return type:

ndarray

Returns:

Current Operator object.

Return type:

cp.ndarray

getMarkedElements()[source]

Returns the marked elements of the operator.

Return type:

list

Returns:

List of marked elements.

Return type:

list

setMarkedElements(markedElements)[source]

Sets the marked elements of the operator.

Return type:

None

Parameters:

markedElements (list) – List of marked elements.

static _degreeDiagonalMatrix(G)[source]

qwak_cupy.ProbabilityDistribution module

class ProbabilityDistribution(state)[source]

Bases: object

Parameters:

state (State)

resetProbDist()[source]
Return type:

None

buildProbDist(state=None)[source]
Return type:

None

Parameters:

state (State)

setProbDist(newProbDist)[source]
Return type:

None

Parameters:

newProbDist (ProbabilityDistribution)

getStateVec()[source]
Return type:

State

getState()[source]
Return type:

State

setState(newState)[source]
Return type:

None

Parameters:

newState (State)

setDim(newDim)[source]
Return type:

None

Parameters:

newDim (int)

getDim()[source]
Return type:

int

setProbVec(newProbVec)[source]
Return type:

None

Parameters:

newProbVec (ndarray)

getProbVec()[source]
Return type:

ndarray

searchNodeProbability(searchNode)[source]
Return type:

float

Parameters:

searchNode (int)

moment(k)[source]
Return type:

float

Parameters:

k (int)

invPartRatio()[source]
Return type:

float

stDev()[source]
Return type:

float

survivalProb(fromNode, toNode)[source]
Return type:

float

qwak_cupy.QuantumWalk module

class QuantumWalk(state, operator)[source]

Bases: object

Parameters:
buildWalk(initState=None, operator=None)[source]
Return type:

None

Parameters:
resetWalk()[source]
Return type:

None

setInitState(newInitState)[source]
Return type:

None

Parameters:

newInitState (State)

getInitState()[source]
Return type:

State

setDim(newDim)[source]
Return type:

None

Parameters:

newDim (int)

getDim()[source]
Return type:

int

setOperator(newOperator)[source]
Return type:

None

Parameters:

newOperator (Operator)

getOperator()[source]
Return type:

Operator

setWalk(newWalk)[source]
Return type:

None

Parameters:

newWalk (QuantumWalk)

getFinalState()[source]
Return type:

State

setFinalState(newFinalState)[source]
Return type:

None

Parameters:

newFinalState (State)

getAmpVec()[source]
Return type:

ndarray

searchNodeAmplitude(searchNode)[source]
Return type:

complex

Parameters:

searchNode (int)

transportEfficiency()[source]
Return type:

float

qwak_cupy.State module

class State(n, nodeList=None, customStateList=None)[source]

Bases: object

Object is initialized with a mandatory user inputted dimension, an optional stateList parameter which will be used to create the amplitudes for each node in the state and an internal stateVec which will be a CuPy ndarray representing the column vector.

Parameters:

  • n (int) – Desired dimension of the state.

  • nodeList (list, optional) – List containing what nodes will have uniform superposition in the state, by default None.

  • customStateList (list, optional) – Custom amplitudes for the state, by default None.

buildState(nodeList=None, customStateList=None)[source]

Builds state vector from state list, by creating a balanced superposition of all nodes in the nodeList.

Return type:

None

Parameters:

  • nodeList (list, optional) – List containing what nodes will have uniform superposition in the state, by default None.

  • customStateList (list, optional) – Custom amplitudes for the state, by default None.

_checkStateOutOfBounds(node)[source]

Checks if the state is out of bounds for the system.

Return type:

None

Parameters:

node (int) – Node to check.

Raises:

StateOutOfBounds – Out of bounds exception.

_checkUnitaryStateList(customStateList)[source]

Checks if the sum of the square of the amplitudes is 1.

Return type:

None

Parameters:

customStateList (list) – Custom state list.

Raises:

NonUnitaryState – Non unitary state exception.

herm()[source]

Returns the Hermitian conjugate of the state vector.

Return type:

ndarray

Returns:

Hermitian conjugate of the state vector.

Return type:

cp.ndarray

inv()[source]

Returns the inverse of the state vector.

Return type:

ndarray

Returns:

Inverse of the state vector.

Return type:

cp.ndarray

resetState()[source]

Resets the components of the State.

Return type:

None

setDim(newDim, newNodeList=None)[source]

Sets the current state dimension to a user defined one.

Return type:

None

Parameters:

  • newDim (int) – New state dimension.

  • newNodeList (list, optional) – List containing the new nodes, by default None.

getDim()[source]

Gets the current state dimension.

Return type:

int

Returns:

State dimension.

Return type:

int

setNodeList(newNodeList)[source]

Sets current node list to a user inputted one.

Return type:

None

Parameters:

newNodeList (list) – List containing the new nodes.

getNodeList()[source]

Gets the current list of nodes.

Return type:

list

Returns:

Current list of nodes.

Return type:

list

setStateVec(newVec)[source]

Sets the column vector associated with the state to a user defined one.

Return type:

None

Parameters:

newVec (cp.ndarray) – New column vector for the state.

getStateVec()[source]

Gets the column vector associated with the state.

Return type:

ndarray

Returns:

Vector of the State.

Return type:

cp.ndarray

setState(newState)[source]

Sets all the parameters of the current state to user defined ones.

Return type:

None

Parameters:

newState (State) – New state.

to_json()[source]

In contrast, the to_json method is not marked with the @classmethod decorator because it is a method that is called on an instance of the State class.

This means that it can access the attributes of the instance on which it is called, and it uses these attributes to generate the JSON string representation of the State instance.

Since it requires access to the attributes of a specific State instance, it cannot be called on the State class itself.

Return type:

str

Returns:

JSON string representation of the State instance.

Return type:

str

classmethod from_json(json_var)[source]

The from_json method is marked with the @classmethod decorator because it is a method that is called on the class itself, rather than on an instance of the class.

This is necessary because it is used to create a new instance of the State class from a JSON string, and it does not require an instance of the State class to do so.

Parameters:

json_var (Union([str, dict])) – JSON string or dictionary representation of the State instance.

Returns:

State instance from JSON string or dictionary representation.

Return type:

State

some_function()[source]

qwak_cupy.qwak module

class QWAK(graph, time=0, timeList=None, gamma=1, initStateList=None, customStateList=None, laplacian=False, markedElements=[], qwakId='userUndef')[source]

Bases: object

Data access class that combines all three components required to perform a continuous-time quantum walk, given by the multiplication of an operator (represented by the Operator class) by an initial state (State class). This multiplication is achieved in the StaticQuantumwalk class, which returns a final state (State Class) representing the amplitudes of each state associated with a graph node. These amplitudes can then be transformed to probability distributions (ProbabilityDistribution class) suitable for plotting with matplotlib, or your package of choice.

Default values for the initial state, time and transition rate are a column vector full of 0s, 0 and 1, respectively. Methods runWalk or buildWalk must then be used to generate the results of the quantum walk.

Parameters:

  • graph (nx.Graph) – NetworkX graph where the walk takes place. Also used for defining the dimensions of the quantum walk.

  • time (float) – Time interval for the quantum walk, by default None.

  • timeList (list) – List with time intervals for multiple walks, by default None.

  • initStateList (list[int], optional) – List with chosen initial states for uniform superposition, by default None

  • customStateList (list[(int,complex)], optional) – Custom init state, by default None.

  • laplacian (bool, optional) – Allows the user to choose whether to use the Laplacian or simple adjacency matrix, by default False.

  • markedElements (list, optional) – List with marked elements for search, by default None.

  • qwakId (str, optional) – User-defined ID for the QWAK instance, by default ‘userUndef’.

  • gamma (float)

runWalk(time=0, initStateList=None, customStateList=None)[source]

Builds class’ attributes, runs the walk and calculates the amplitudes and probability distributions with the given parameters. These can be accessed with their respective get methods.

Return type:

None

Parameters:

  • time (float, optional) – Time for which to calculate the quantum walk, by default 0.

  • initStateList (list[int], optional) – List with chosen initial states for uniform superposition, by default None.

  • customStateList (list[(int,complex)], optional) – Custom init state, by default None.

Raises:
runExpmWalk(time=0, initStateList=None, customStateList=None)[source]

Builds class’ attributes, runs the walk and calculates the amplitudes and probability distributions with the given parameters. These can be accessed with their respective get methods.

Return type:

None

Parameters:

  • time (float, optional) – Time for which to calculate the quantum walk, by default 0.

  • initStateList (list[int], optional) – List with chosen initial states for uniform superposition, by default None.

  • customStateList (list[(int,complex)], optional) – Custom init state, by default None.

Raises:
runMultipleWalks(timeList=None, initStateList=None, customStateList=None)[source]

Runs the walk for multiple times and stores the probability distributions in a list.

Return type:

None

Parameters:

  • timeList (list, optional) – List of times for which to calculate the quantum walk, by default None.

  • initStateList (list, optional) – List with chosen initial states for uniform superposition, by default None.

  • customStateList (list, optional) – Custom init state, by default None.

Raises:

UndefinedTimeList – Raised when the timeList is None.

runMultipleExpmWalks(timeList=None, initStateList=None, customStateList=None)[source]

Runs the walk for multiple times and stores the probability distributions in a list.

Return type:

None

Parameters:

  • timeList (list, optional) – List of times for which to calculate the quantum walk, by default None.

  • initStateList (list, optional) – List with chosen initial states for uniform superposition, by default None.

  • customStateList (list, optional) – Custom init state, by default None.

Raises:

UndefinedTimeList – Raised when the timeList is None.

resetWalk()[source]

Resets the components of a walk.

Return type:

None

setDim(newDim, graphStr=None, graph=None, initStateList=None)[source]

Sets the current walk dimensions to a user defined one. Also takes a graph string to be evaluated and executed as a NetworkX graph generator.

Return type:

None

Parameters:

  • newDim (int) – New dimension for the quantum walk.

  • graphStr (str) – Graph string to generate the graph with the new dimension.

  • graph (nx.Graph, optional) – Graph with the new dimension.

  • initStateList (list[int], optional) – Init state list with new dimension.

getGraph()[source]

Gets the current graph.

Return type:

Graph

Returns:

Current graph.

Return type:

nx.Graph

getDim()[source]

Gets the current graph dimension.

Return type:

int

Returns:

Dimension of graph.

Return type:

int

setGraph(newGraph, initStateList=None)[source]

Sets the current graph to a user defined one. Also recalculates the current operator and walk dimension.

Return type:

None

Parameters:

newGraph (nx.Graph) – New NetworkX graph.

setCustomGraph(customAdjMatrix)[source]

Sets the current graph to a user defined one.

Return type:

None

Parameters:

customAdjMatrix (cp.ndarray) – Adjacency matrix of the new graph.

setInitState(newInitState)[source]

Sets the current initial state to a user defined one.

Return type:

None

Parameters:

newInitState (State) – New initial state.

setTime(newTime)[source]

Sets the current walk time to a user defined one.

Return type:

None

Parameters:

newTime (float) – New time.

setTimeList(newTimeList)[source]

Sets the current walk time to a user defined one.

Return type:

None

Parameters:

newTimeList (list) – New time list.

getTime()[source]

Gets the current walk time.

Return type:

float

Returns:

Current value of time.

Return type:

float

getTimeList()[source]

Gets the current walk time.

Return type:

float

Returns:

Current value of time.

Return type:

float

setAdjacencyMatrix(newAdjMatrix, initStateList=None)[source]

Sets the current adjacency matrix to a user defined one.

Return type:

None

Parameters:

  • newAdjMatrix (cp.ndarray) – New adjacency matrix.

  • initStateList (list, optional) – New initial state list, by default None.

getAdjacencyMatrix()[source]

Gets the current adjacency matrix.

Return type:

ndarray

Returns:

Current adjacency matrix.

Return type:

cp.ndarray

setHamiltonian(newHamiltonian)[source]

Sets the current Hamiltonian to a user defined one.

Return type:

None

Parameters:

newHamiltonian (cp.ndarray) – New Hamiltonian.

getHamiltonian()[source]

Gets the current Hamiltonian.

Return type:

ndarray

Returns:

Current Hamiltonian.

Return type:

cp.ndarray

setOperator(newOperator)[source]

Sets the current walk operator a user defined one.

Return type:

None

Parameters:

newOperator (Operator) – New operator object.

getOperator()[source]

Gets the current walk operator.

Return type:

Operator

Returns:

Current operator object.

Return type:

Operator

setWalk(newWalk)[source]

Sets current walk amplitudes to a user defined state. This might not be needed and removed in the future.

Return type:

None

Parameters:

newWalk (State) – New walk amplitudes.

getWalk()[source]

Gets current QuantumWalk object

Return type:

QuantumWalk

Returns:

Current state amplitudes.

Return type:

QuantumWalk

getFinalState()[source]

Gets current QuantumWalk State.

Return type:

State

Returns:

State of the QuantumWalk.

Return type:

State

getAmpVec()[source]

Gets the array of the QuantumWalk state.

Return type:

ndarray

Returns:

Array of the QuantumWalk state.

Return type:

cp.ndarray

setProbDist(newProbDist)[source]

Sets current walk probability distribution to a user defined one. This might not be needed and removed in the future.

Return type:

None

Parameters:

newProbDist (ProbabilityDistribution) – New probability distribution.

getProbDist()[source]

Gets the current probability distribution.

Return type:

ProbabilityDistribution

Returns:

ProbabilityDistribution object.

Return type:

ProbabilityDistribution

getProbDistList()[source]

Returns a list of probability distributions in the case of multiple walks.

Return type:

list

Returns:

List of ProbabilityDistribution objects.

Return type:

list

setProbDistList(newProbDistList)[source]

Sets the current probability distribution list to a user defined one.

Return type:

None

Parameters:

newProbDistList (list) – New probability distribution list.

getProbVec()[source]

Gets the current probability distribution vector.

Return type:

ndarray

Returns:

Probability Distribution vector.

Return type:

cp.ndarray

getProbVecList()[source]

Returns a list of probability distribution vectors in the case of multiple walks.

Return type:

list

Returns:

List of probability distribution vectors.

Return type:

list

setQWAK(newQWAK)[source]

Sets the QWAK instance’s attributes to the ones of the given QWAK instance.

Return type:

None

Parameters:

newQWAK (QWAK) – QWAK instance to copy the attributes from.

searchNodeAmplitude(searchNode)[source]

User inputted node for search

Return type:

complex

Parameters:

searchNode (int) – User inputted node for the search.

Returns:

Amplitude associated with the search node.

Return type:

complex

searchNodeProbability(searchNode)[source]

Searches and gets the probability associated with a given node.

Return type:

float

Parameters:

searchNode (int) – User inputted node for the search.

Returns:

Probability associated with the search node.

Return type:

float

getMean(resultRounding=None)[source]

Gets the mean of the probability distribution.

Return type:

float

Parameters:

resultRounding (int, optional) – Rounding of the result, by default None.

Returns:

Mean of the probability distribution.

Return type:

float

getMeanList(resultRounding=None)[source]

Gets the mean of the probability distribution list.

Return type:

list

Parameters:

resultRounding (int, optional) – Rounding of the results, by default None.

Returns:

List of means of the probability distributions.

Return type:

list

getSndMoment(resultRounding=None)[source]

Gets the second moment of the probability distribution.

Return type:

float

Parameters:

resultRounding (int, optional) – Rounding of the result, by default None.

Returns:

Second moment of the probability distribution.

Return type:

float

getStDev(resultRounding=None)[source]

Gets the standard deviation of the probability distribution.

Return type:

float

Parameters:

resultRounding (int, optional) – Rounding of the result, by default None.

Returns:

Standard deviation of the probability distribution.

Return type:

float

getStDevList(resultRounding=None)[source]

Gets the standard deviation of the probability distribution list.

Return type:

list

Parameters:

resultRounding (int, optional) – Rounding of the results, by default None.

Returns:

List of standard deviations of the probability distributions.

Return type:

list

getInversePartRatio(resultRounding=None)[source]

Gets the inverse participation ratio of the probability distribution.

Return type:

float

Parameters:

resultRounding (int, optional) – Rounding of the result, by default None.

Returns:

Inverse participation ratio of the probability distribution.

Return type:

float

getInversePartRatioList(resultRounding=None)[source]

Gets the inverse participation ratio of the probability distribution list.

Return type:

list

Parameters:

resultRounding (int, optional) – Rounding of the results, by default None.

Returns:

List of inverse participation ratios of the probability distributions.

Return type:

list

getSurvivalProb(fromNode, toNode, resultRounding=None)[source]

Gets the survival probability of the probability distribution.

Return type:

float

Parameters:

  • fromNode (int) – Starting node.

  • toNode (int) – Ending node.

  • resultRounding (int, optional) – Rounding of the result, by default None.

Returns:

Survival probability of the probability distribution.

Return type:

float

Raises:

MissingNodeInput – Missing input node error.

getSurvivalProbList(fromNode, toNode, resultRounding=None)[source]

Gets the survival probability of the probability distribution list.

Return type:

list

Parameters:

  • fromNode (int) – Starting node.

  • toNode (int) – Ending node.

  • resultRounding (int, optional) – Rounding of the results, by default None.

Returns:

List of survival probabilities of the probability distributions.

Return type:

list

Raises:

MissingNodeInput – Missing input node error.

Module contents