util.hpp File Reference

#include <petscmat.h>
#include <cctype>
#include <cstring>
#include <map>
#include <optional>
#include <string>
#include <fstream>
#include <iostream>
#include <vector>
#include "version.hpp"

Include dependency graph for util.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	ParsedArgs
	Structure for parsed command-line arguments. More...

Functions
void	printHelp ()
ParsedArgs	parseArguments (int argc, char **argv)
double	sigmoid (double width, double x)
	Sigmoid function for smooth transitions.
double	sigmoid_diff (double width, double x)
	Derivative of sigmoid function.
double	getRampFactor (const double time, const double tstart, const double tstop, const double tramp)
	Computes ramping factor for control pulse shaping.
double	getRampFactor_diff (const double time, const double tstart, const double tstop, const double tramp)
	Derivative of ramping factor with respect to stop time.
PetscInt	getVecID (const PetscInt row, const PetscInt col, const PetscInt dim)
	Returns vectorized index for matrix element (row,col).
PetscInt	mapEssToFull (const PetscInt i, const std::vector< size_t > &nlevels, const std::vector< size_t > &nessential)
	Maps index from essential level system to full-dimension system.
PetscInt	mapFullToEss (const PetscInt i, const std::vector< size_t > &nlevels, const std::vector< size_t > &nessential)
	Maps index from full dimension to essential dimension system.
int	isEssential (const int i, const std::vector< size_t > &nlevels, const std::vector< size_t > &nessential)
	Tests if density matrix index corresponds to an essential level.
int	isGuardLevel (const int i, const std::vector< size_t > &nlevels, const std::vector< size_t > &nessential)
	Tests if density matrix index corresponds to a guard level.
PetscErrorCode	Ikron (const Mat A, const int dimI, const double alpha, Mat *Out, InsertMode insert_mode)
	Computes Kronecker product \(Id \otimes A\).
PetscErrorCode	kronI (const Mat A, const int dimI, const double alpha, Mat *Out, InsertMode insert_mode)
	Computes Kronecker product \(A \otimes Id\).
PetscErrorCode	AkronB (const Mat A, const Mat B, const double alpha, Mat *Out, InsertMode insert_mode)
	Computes general Kronecker product \(A \otimes B\).
PetscErrorCode	MatIsAntiSymmetric (Mat A, PetscReal tol, PetscBool *flag)
	Tests if matrix A is anti-symmetric (A^T = -A).
PetscErrorCode	StateIsHermitian (Vec x, PetscReal tol, PetscBool *flag)
	Tests if vectorized state represents a Hermitian matrix.
PetscErrorCode	StateHasTrace1 (Vec x, PetscReal tol, PetscBool *flag)
	Tests if vectorized state vector x=[u,v] represents matrix with trace 1.
PetscErrorCode	SanityTests (Vec x, PetscReal time)
	Performs all sanity tests on state vector.
int	read_vector (const char *filename, double *var, int dim, bool quietmode=false, int skiplines=0, const std::string testheader="")
	Reads data vector from file.
int	getEigvals (const Mat A, const int neigvals, std::vector< double > &eigvals, std::vector< Vec > &eigvecs)
	Computes eigenvalues and eigenvectors of matrix A.
bool	isUnitary (const Mat A, const Mat B)
	Tests if complex matrix A+iB is unitary.
template<typename Tval >
void	copyLast (std::vector< Tval > &fillme, int tosize)
	Extends vector by repeating the last element.
std::string	toLower (std::string str)
	Returns a lowercase version of the input string.
bool	hasSuffix (const std::string &str, const std::string &suffix)
	Checks if string ends with specified suffix.
template<typename T >
std::optional< T >	parseEnum (const std::string &str, const std::map< std::string, T > &enum_map)
	Generic enum parsing utility with case-insensitive lookup.
template<typename EnumType >
std::string	enumToString (EnumType value, const std::map< std::string, EnumType > &type_map)
	Converts enum value back to string.
template<typename T >
T	parseEnum (const std::optional< std::string > &opt_str, const std::map< std::string, T > &enum_map, const T &default_value)
	Generic enum parsing utility with case-insensitive lookup and default fallback.

Function Documentation

AkronB()

PetscErrorCode AkronB	(	const Mat	A,
		const Mat	B,
		const double	alpha,
		Mat *	Out,
		InsertMode	insert_mode
	)

Computes general Kronecker product \(A \otimes B\).

Computes the Kronecker product of two arbitrary matrices A and B. Works in PETSc serial mode only. Output matrix must be pre-allocated and should be assembled afterwards.

Parameters

A	First input matrix
B	Second input matrix
alpha	Scaling factor
Out	Output matrix \((A \otimes B)\)
insert_mode	INSERT_VALUES or ADD_VALUES

Returns

PetscErrorCode Error code

copyLast()

template<typename Tval >

void copyLast	(	std::vector< Tval > &	fillme,
		int	tosize
	)

Extends vector by repeating the last element.

Template function that fills a vector to the specified size by repeating the last element.

Parameters

fillme	Vector to extend
tosize	Target size for the vector

enumToString()

template<typename EnumType >

std::string enumToString	(	EnumType	value,
		const std::map< std::string, EnumType > &	type_map
	)

Converts enum value back to string.

Parameters

value	Enum value to convert
type_map	Map from string to enum values

Returns

std::string String representation of enum value

getEigvals()

int getEigvals	(	const Mat	A,
		const int	neigvals,
		std::vector< double > &	eigvals,
		std::vector< Vec > &	eigvecs
	)

Computes eigenvalues and eigenvectors of matrix A.

Requires compilation with SLEPc for eigenvalue computations.

Parameters

A	Input matrix
neigvals	Number of eigenvalues to compute
eigvals	Vector to store eigenvalues
eigvecs	Vector to store eigenvectors

Returns

int Error code

getRampFactor()

double getRampFactor	(	const double	time,
		const double	tstart,
		const double	tstop,
		const double	tramp
	)

Computes ramping factor for control pulse shaping.

Computes smooth ramping factor for interval [tstart, tstop] using sigmoid transitions with specified width tramp.

Parameters

time	Current time
tstart	Start time of interval
tstop	Stop time of interval
tramp	Ramping transition width

Returns

double Ramping factor between 0 and 1

getRampFactor_diff()

double getRampFactor_diff	(	const double	time,
		const double	tstart,
		const double	tstop,
		const double	tramp
	)

Derivative of ramping factor with respect to stop time.

Parameters

time	Current time
tstart	Start time of interval
tstop	Stop time of interval
tramp	Ramping transition width

Returns

double Derivative with respect to tstop

getVecID()

PetscInt getVecID	(	const PetscInt	row,
		const PetscInt	col,
		const PetscInt	dim
	)

Returns vectorized index for matrix element (row,col).

Parameters

row	Matrix row index
col	Matrix column index
dim	Matrix dimension

Returns

int Vectorized index for element (row,col)

hasSuffix()

bool hasSuffix	(	const std::string &	str,
		const std::string &	suffix
	)

Checks if string ends with specified suffix.

Parameters

str	Input string to check.
suffix	Suffix to look for.

Returns

bool True if string ends with suffix, false otherwise.

Ikron()

PetscErrorCode Ikron	(	const Mat	A,
		const int	dimI,
		const double	alpha,
		Mat *	Out,
		InsertMode	insert_mode
	)

Computes Kronecker product \(Id \otimes A\).

Computes the Kronecker product of an identity matrix with matrix A. Output matrix must be pre-allocated with sufficient non-zeros A * dimI.

Parameters

[in]	A	Input matrix
[in]	dimI	Dimension of identity matrix
[in]	alpha	Scaling factor
[out]	Out	Output matrix \((Id \otimes A)\)
[in]	insert_mode	INSERT_VALUES or ADD_VALUES

Returns

PetscErrorCode Error code

isEssential()

int isEssential	(	const int	i,
		const std::vector< size_t > &	nlevels,
		const std::vector< size_t > &	nessential
	)

Tests if density matrix index corresponds to an essential level.

Parameters

i	Row/column index of density matrix
nlevels	Number of levels per oscillator
nessential	Number of essential levels per oscillator

Returns

int Non-zero if index corresponds to essential level

isGuardLevel()

int isGuardLevel	(	const int	i,
		const std::vector< size_t > &	nlevels,
		const std::vector< size_t > &	nessential
	)

Tests if density matrix index corresponds to a guard level.

A guard level is the highest energy level of an oscillator, used for leakage detection and prevention.

Parameters

i	Row/column index of density matrix
nlevels	Number of levels per oscillator
nessential	Number of essential levels per oscillator

Returns

int Non-zero if index corresponds to guard level

isUnitary()

bool isUnitary	(	const Mat	A,
		const Mat	B
	)

Tests if complex matrix A+iB is unitary.

Tests whether (A+iB)(A+iB)^dagger = I for real matrices A and B.

Parameters

A	Real part of complex matrix
B	Imaginary part of complex matrix

Returns

bool True if matrix is unitary

kronI()

PetscErrorCode kronI	(	const Mat	A,
		const int	dimI,
		const double	alpha,
		Mat *	Out,
		InsertMode	insert_mode
	)

Computes Kronecker product \(A \otimes Id\).

Computes the Kronecker product of matrix A with an identity matrix. Output matrix must be pre-allocated with sufficient non-zeros A * dimI.

Parameters

[in]	A	Input matrix
[in]	dimI	Dimension of identity matrix
[in]	alpha	Scaling factor
[out]	Out	Output matrix \((A \otimes Id)\)
[in]	insert_mode	INSERT_VALUES or ADD_VALUES

Returns

PetscErrorCode Error code

mapEssToFull()

PetscInt mapEssToFull	(	const PetscInt	i,
		const std::vector< size_t > &	nlevels,
		const std::vector< size_t > &	nessential
	)

Maps index from essential level system to full-dimension system.

Parameters

i	Index in essential level system
nlevels	Number of levels per oscillator
nessential	Number of essential levels per oscillator

Returns

int Corresponding index in full-dimension system

mapFullToEss()

PetscInt mapFullToEss	(	const PetscInt	i,
		const std::vector< size_t > &	nlevels,
		const std::vector< size_t > &	nessential
	)

Maps index from full dimension to essential dimension system.

Parameters

i	Index in full dimension system
nlevels	Number of levels per oscillator
nessential	Number of essential levels per oscillator

Returns

int Corresponding index in essential dimension system

MatIsAntiSymmetric()

PetscErrorCode MatIsAntiSymmetric	(	Mat	A,
		PetscReal	tol,
		PetscBool *	flag
	)

Tests if matrix A is anti-symmetric (A^T = -A).

Parameters

A	Input matrix to test
tol	Tolerance for comparison
flag	Output flag indicating anti-symmetry

Returns

PetscErrorCode Error code

parseArguments()

ParsedArgs parseArguments	(	int	argc,
		char **	argv
	)

Parses command-line arguments for the Quandary program.

Parameters

argc	Number of command-line arguments.
argv	Array of command-line argument strings.

Returns

ParsedArgs structure containing configuration filename, quiet mode flag, and PETSc options.

parseEnum() [1/2]

template<typename T >

T parseEnum	(	const std::optional< std::string > &	opt_str,
		const std::map< std::string, T > &	enum_map,
		const T &	default_value
	)

Generic enum parsing utility with case-insensitive lookup and default fallback.

Parameters

opt_str	Optional string value to parse into enum
enum_map	Map from string to enum values
default_value	Default enum value to return if string is missing or invalid

Returns

T Parsed enum value or default_value if not found

parseEnum() [2/2]

template<typename T >

std::optional< T > parseEnum	(	const std::string &	str,
		const std::map< std::string, T > &	enum_map
	)

Generic enum parsing utility with case-insensitive lookup.

Parameters

str	String value to parse into enum
enum_map	Map from string to enum values

Returns

std::optional<T> Parsed enum value or nullopt if not found

printHelp()

void printHelp

(

)

Prints help message for command-line usage.

read_vector()

int read_vector	(	const char *	filename,
		double *	var,
		int	dim,
		bool	quietmode = false,
		int	skiplines = 0,
		const std::string	testheader = ""
	)

Reads data vector from file.

Parameters

filename	Name of file to read
var	Array to store data
dim	Dimension of data to read
quietmode	Flag for reduced output
skiplines	Number of header lines to skip
testheader	Expected header string for validation

Returns

int Error code

SanityTests()

PetscErrorCode SanityTests	(	Vec	x,
		PetscReal	time
	)

Performs all sanity tests on state vector.

Parameters

x	State vector to test
time	Current time for diagnostic output

Returns

PetscErrorCode Error code

sigmoid()

double sigmoid	(	double	width,
		double	x
	)

Sigmoid function for smooth transitions.

Parameters

width	Transition width parameter
x	Input value

Returns

double Sigmoid function value

sigmoid_diff()

double sigmoid_diff	(	double	width,
		double	x
	)

Derivative of sigmoid function.

Parameters

width	Transition width parameter
x	Input value

Returns

double Derivative of sigmoid function

StateHasTrace1()

PetscErrorCode StateHasTrace1	(	Vec	x,
		PetscReal	tol,
		PetscBool *	flag
	)

Tests if vectorized state vector x=[u,v] represents matrix with trace 1.

Parameters

x	Vectorized state vector
tol	Tolerance for comparison
flag	Output flag indicating unit trace

Returns

PetscErrorCode Error code

StateIsHermitian()

PetscErrorCode StateIsHermitian	(	Vec	x,
		PetscReal	tol,
		PetscBool *	flag
	)

Tests if vectorized state represents a Hermitian matrix.

For vectorized state x=[u,v] to represent a Hermitian matrix, u must be symmetric and v must be anti-symmetric.

Parameters

x	Vectorized state vector
tol	Tolerance for comparison
flag	Output flag indicating Hermiticity

Returns

PetscErrorCode Error code

toLower()

std::string toLower

(

std::string

str

)

Returns a lowercase version of the input string.

Parameters

str	String to convert to lowercase.

Returns

std::string Lowercase string