inquanto.core¶

Logging and Timing¶

class Timer¶

Bases: object

Simple Timer.

start()¶

Starts timer.

Return type:: None

stop()¶

Stops timer.

Return type:: None

class TimerWith(name=None, process=False)¶

Bases: object

Basic timer context manager.

Parameters:

name (Optional[str], default: None) – Name for the context.
process (bool, default: False) – Whether to use process timing.

Examples

>>> with TimerWith():
...    for i in range(1000000):
...        a = i ** 2 
#...
#...
>>> with TimerWith("OUTER"):
...     for i in range(1000000):
...         a = i ** 2
...     with TimerWith("INNER"):
...         for i in range(1000000):
...             a = i ** 2 
#...
#...
#...
#...

block_counter = 0¶

class InQuantoContext(job_name, working_file_name=None, file_only=False)¶

Bases: object

Context to log into a file during a calculation.

Parameters:

job_name (str) – Name of the job (this will be part of the file name).
working_file_name (Optional[str], default: None) – Name of this file, for example "__file__".
file_only (bool, default: False) – Whether to suppress std outputs.

property base: str¶: Filename base.

property prefix: str¶: Filename prefix.

Parameters¶

class SymbolEnsemble(symbols)¶

Bases: object

An ensemble manager for symbolic variables.

This class provides methods to generate dictionaries of symbolic variables with either random Gaussian-distributed values or values set to zero.

Parameters:: symbols (list[Symbol]) –

as_list()¶

Returns the list of symbols.

Return type:: list[Symbol]

as_set()¶

Returns the list of symbols.

Return type:: set[Symbol]

construct_from_array(array)¶

Constructs a dictionary by mapping the instance’s symbols to the provided array of values.

Parameters:: array (Union[ndarray, list]) – An array containing values to be assigned to the instance’s symbols.
Returns:: dict – A dictionary mapping symbols to their corresponding values from the array.
Raises:: AssertionError – If the length of the input array does not match the number of symbols in the instance.

construct_from_dict(other)¶

Constructs a dictionary given a symbol-to-value map.

The new dictionairy contains all the symbols from the original list, with values assigned according to other.

Parameters:: other (dict) – A symbol-to-value map.
Returns:: dict – A new dictionary with symbols as keys and values from other.
Raises:: RuntimeError – When other does not contain any symbols from the original list.

construct_random(seed=0, mu=0.0, sigma=1.0)¶

Constructs a dictionary with random values for the symbols.

The new dictionary contains all symbols from the original list, with values drawn randomly from a Gaussian distribution.

Parameters:

seed (default: 0) – Seed for random number generation.
mu (default: 0.0) – Mean of the distribution.
sigma (default: 1.0) – Standard deviation of the distribution.

Returns:

dict – New dictionary with symbols as keys and random values as values.

construct_zeros()¶

Constructs a dictionary with all values set to zero.

The new dictionary contains all symbols from the original list, with values set to zero.

Returns:: dict – New dictionary with symbols as keys and values set to zero.

copy()¶

Returns a deep copy of the current SymbolEnsemble, retaining the order of symbols.

Return type:: SymbolEnsemble

static from_symbols(symbols)¶

Creates a SymbolEnsemble instance from a list of symbols.

Parameters:: symbols (list[Symbol]) –

issubset(other)¶: Checks if all elements of this SymbolEnsemble are present in another collection.

update(other)¶

Updates the current SymbolEnsemble with another and returns itself.

Parameters:: other (Union[SymbolEnsemble, dict[Symbol, Any]]) –
Return type:: SymbolEnsemble

Methods¶

InQuanto’s core module containing utility methods and classes useful in multiple submodules.

class CacheDict(hashers=None, max_size_in_bytes=None, ignore_make_hashable=True)¶

Bases: MutableMapping

Dictionary which admits the use of object addresses as hashes.

Some objects may not have a hash method available, and for some others a hash may be expensive to compute, this class provides a safe way to use the object’s address (aka id) as the hash. Hashing by address is not equivalent to hashing by value, since looking up a copy of an object will not find an existing key with the same value, since by virtue of their different addresses, their hashes will in general differ.

This structure keeps track of these address-hashed instances that appear in the keys and values, either as the keys and values themselves, or as elements of tuple-typed keys or values. This is done using the weakref module which retains non lifetime-preserving references to objects.

Parameters:

hashers (Dict, default: None) – Dict mapping from type to the function that should be called to hash objects of that type
max_size_in_bytes (int, default: None) –
ignore_make_hashable (bool, default: True) –

attempt(key, value_fn)¶

Try to access the cached value, if it’s missing, get the value by calling the given function.

Parameters:

key (Any) – key object or tuple of key objects.
value_fn (Callable[[], Any]) – callable whose result is the value

Returns:

tuple[bool, Any] – Hit success boolean, and the value.

clear() → None. Remove all items from D.¶

static convert_weaks_to_refs(obj)¶

Convert weak refs to strong refs for access.

Parameters:: obj (Any) –
Return type:: Any

static format_size(n_byte)¶

Get the size as a string using standard suffixes.

Parameters:: n_byte (int) –
Return type:: str

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

static get_size_in_bytes(obj)¶

Get the size of a key or value.

Parameters:: obj (Any) –
Return type:: int

items()¶: Get an iterator over the keys-value pairs.

keys()¶: Get an iterator over the keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair¶: as a 2-tuple; but raise KeyError if D is empty.

report()¶

Returns a pandas DataFrame object containing a report of the current state of cache.

Return type:: DataFrame

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶

update([E, ]**F) → None. Update D from mapping/iterable E and F.¶: If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values()¶: Get an iterator over the values.

class SymbolEnsemble(symbols)¶

Bases: object

An ensemble manager for symbolic variables.

This class provides methods to generate dictionaries of symbolic variables with either random Gaussian-distributed values or values set to zero.

Parameters:: symbols (list[Symbol]) –

as_list()¶

Returns the list of symbols.

Return type:: list[Symbol]

as_set()¶

Returns the list of symbols.

Return type:: set[Symbol]

construct_from_array(array)¶

Constructs a dictionary by mapping the instance’s symbols to the provided array of values.

Parameters:: array (Union[ndarray, list]) – An array containing values to be assigned to the instance’s symbols.
Returns:: dict – A dictionary mapping symbols to their corresponding values from the array.
Raises:: AssertionError – If the length of the input array does not match the number of symbols in the instance.

construct_from_dict(other)¶

Constructs a dictionary given a symbol-to-value map.

The new dictionairy contains all the symbols from the original list, with values assigned according to other.

Parameters:: other (dict) – A symbol-to-value map.
Returns:: dict – A new dictionary with symbols as keys and values from other.
Raises:: RuntimeError – When other does not contain any symbols from the original list.

construct_random(seed=0, mu=0.0, sigma=1.0)¶

Constructs a dictionary with random values for the symbols.

The new dictionary contains all symbols from the original list, with values drawn randomly from a Gaussian distribution.

Parameters:

seed (default: 0) – Seed for random number generation.
mu (default: 0.0) – Mean of the distribution.
sigma (default: 1.0) – Standard deviation of the distribution.

Returns:

dict – New dictionary with symbols as keys and random values as values.

construct_zeros()¶

Constructs a dictionary with all values set to zero.

The new dictionary contains all symbols from the original list, with values set to zero.

Returns:: dict – New dictionary with symbols as keys and values set to zero.

copy()¶

Returns a deep copy of the current SymbolEnsemble, retaining the order of symbols.

Return type:: SymbolEnsemble

static from_symbols(symbols)¶

Creates a SymbolEnsemble instance from a list of symbols.

Parameters:: symbols (list[Symbol]) –

issubset(other)¶: Checks if all elements of this SymbolEnsemble are present in another collection.

update(other)¶

Updates the current SymbolEnsemble with another and returns itself.

Parameters:: other (Union[SymbolEnsemble, dict[Symbol, Any]]) –
Return type:: SymbolEnsemble

cached(func=None, timer=None, *, cache_dict=None)¶

Decorates a function, adding caching functionality to it.

If a cached evaluation of func corresponding to the args and kwargs passed in, the result will be returned without reevaluation of func.

Parameters:

func (Callable[..., Any], default: None) – A function or class method to be wrapped (cached).
cache_dict (CacheDict, default: None) – A store for all previous evaluations of func that fit within a specified memory limit.
timer (CacheTimer, default: None) –

Returns:

Callable[..., Any] – Wrapped function, ensuring caching functionality.

Raises:

ValueError – When there is no cache-handling class argument passed.

dict_to_matrix(ordered_symbols, symbol_pair_to_value)¶

Return a matrix of values with specified order.

Parameters:

ordered_symbols (Sequence[Symbol]) – Sequence of symbols defining output order.
symbol_pair_to_value (dict[tuple[Symbol, Symbol], float]) – Map of symbol-pairs to values.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – Matrix of values with axes ordered according to ordered_symbols.

dict_to_vector(ordered_symbols, symbol_to_value)¶

Return an array of values with specified order.

Parameters:

ordered_symbols (Sequence[Symbol]) – Sequence of symbols defining output order.
symbol_to_value (dict[str | Symbol, Union[int, float, complex, Expr]]) – Map of symbols to values.

Returns:

ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – Values ordered according to ordered_symbols.

hash_data(data)¶

Creates a consistent hash string from the given data using xxhash.

The function supports both string and tuple data types.

Parameters:: data (Union[str, Tuple[TypeHasStr, ...]]) – The data to hash, should be either a string or a tuple.
Returns:: str – A string representation of the hashed data.
Raises:: TypeError – If the input data is not a string or a tuple.

Examples

>>> print(hash_data("Hello World"))
MIYWMZBRGZSWK

>>> print(hash_data(('Hello', 'World')))
HAYDOYJYMU4DE

>>> print(hash_data('Hello,World'))
HAYDOYJYMU4DE

Note: The hash value for a string and a tuple containing the same strings will be identical.

matrix_to_dict(ordered_symbols, matrix)¶

Converts a matrix of values to a map of symbol-pairs to values.

Parameters:

ordered_symbols (Sequence[Symbol]) – Sequence of symbols defining output order.
matrix (ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – Matrix of values to be assigned to symbol-pairs.

Returns:

dict[tuple[Symbol, Symbol], float] – Map of symbol-pairs to values.

pd_safe_eigh(h, s, lindep=LINDEP_TOLERANCE_STRICTER)¶

Solves the generalized eigenvalue problem \(HC = SCE\).

\(H\) and \(S\) are square matrices, and \(C\) is a matrix of eigenvectors. The matrices \(H\) and \(S\) are usually Hermitian (or symmetric if real) and \(S\) is positive definite.

Parameters:

h (ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – Hermitian matrix.
s (ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – Hermitian matrix.
lindep (float, default: LINDEP_TOLERANCE_STRICTER) – Tolerance to determine linear dependency. Diagonalizing \(S\) identifies eigenvectors as linearly dependent subsets when their corresponding eigenvalues fall below the specified threshold.

Returns:

tuple[ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]] – Eigenvalues \(E\) in the linearly independent subspace, matrix of eigenvectors \(C\), and eigenvalues of \(S\).

vector_to_dict(ordered_symbols, vector)¶

Converts a vector of values to a symbol-value map.

Parameters:

ordered_symbols (Sequence[Symbol]) – Sequence of symbols defining output order.
vector (ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – Values to be assigned to symbols.

Returns:

dict[Symbol, float] – Map of symbols to values.