Karana.Core

Core modules and classes.

These are foundational and utilized by many of the other packages and modules.

Attributes

Json
T

Classes

CppWeakRef	Weak reference to C++ object.
Base	Common base class used by most simulation objects.
BaseContainer	Container class that holds all the Base objects.
CppWeakRefBase
DebugManager
DumpOptionsBase
DumpOptionsLockingBase
JsonLogger	Base class for json loggers. Json log information will come in on the
LockingBase	Locking version of the Base class. This is the base class but with
LogLevel	Members:
MsgLogger

Functions

deprecated(…)	Use this decorator is used to mark functions or classes as deprecated.
allDestroyed(→ bool)	Checks if all Base objects have been destroyed.
allHealthy(→ bool)	Checks whether all non-DataCache objects are healthy
allReady(→ bool)	Checks is the params for all the Base objects in the provided
debug(…)	Write an debug to all loggers using a function that outputs a message.
debugJson(…)	Write an debug to all loggers using the provided ordered json and
discard(…)	Discard a sequence of Bases.
error(…)	Write an error to all loggers using a function that outputs a message.
findShareDir(→ pathlib.Path)	Find the /share/Karana path on the system respecting the
info(…)	Write an info to all loggers using a function that outputs a message.
numTrace(…)	Write an num_trace to all loggers using a function that outputs a
trace(…)	Write an trace to all loggers using a function that outputs a message.
traceJson(…)	Write an trace to all loggers using the provided ordered json and
warn(…)	Write an warn to all loggers using a function that outputs a message.

Package Contents

type Karana.Core.Json = dict[str, str | int | float | 'Json']

Karana.Core.deprecated(name: str, removal_date: datetime.date | str, msg: str)

Karana.Core.deprecated(removal_date: datetime.date | str, msg: str)

Use this decorator is used to mark functions or classes as deprecated.

See overloaded function signatures for details.

Karana.Core.T

class Karana.Core.CppWeakRef(base: T)

Bases: CppWeakRefBase, Generic[T]

Weak reference to C++ object.

Use the get() method to return a Python object from the C++ object if it exists.

__call__() → T | None

Return a Python object for the C++ class if it exists, or None if it does not.

Returns:

The Python object if the C++ object still exists. None if it does not.

Return type:

T | None

class Karana.Core.Base(name: str)

Common base class used by most simulation objects.

dump(prefix: str = '', options: DumpOptionsBase = None) → None

Print dumpString on std::cout.

Parameters:

• prefix – A string to use as prefix for each output line

• options – Struct with options to tailor the output

dumpString(prefix: str = '', options: DumpOptionsBase = None) → str

Return information about the object.

Parameters:

• prefix – A string to use as prefix for each output line

• options – Struct with options to tailor the output

Returns:

String with the information about the object.

id() → int

id of this object. :returns: id of this object.

isReady() → bool

Checks is the params for the object have been initialized. :returns: True if the params have set up.

name() → str

Name of this object. :returns: Name of this object.

typeString() → str

Returns the type string of Base. :returns: The type string.

class Karana.Core.BaseContainer

Container class that holds all the Base objects.

The BaseContainer provides named storage and access to Base objects using unique IDs. It supports range-based iteration and is designed to allow insertion and erasure by friend class Base.

at_exit_fns: _VoidCallbackRegistry

check_all_destroyed: bool

static singleton() → BaseContainer

Gets the singleton BaseContainer instance.

Returns:

A shared pointer to the singleton BaseContainer.

__iter__() → collections.abc.Iterator[tuple[int, Base]]

at(arg0: SupportsInt) → Base

Retrieves the Base pointer associated with the given ID.

Parameters:

id – The ID of the desired Base object.

Returns:

A pointer to the Base object, or nullptr if not found.

atLockingBase(arg0: SupportsInt) → LockingBase | None

Look for a Base at the given ID. Try to convert it to a LockingBase

contains(arg0: SupportsInt) → bool

Checks whether the container has an entry with the given ID.

Parameters:

id – The ID to check for.

Returns:

True if the ID is present; otherwise, false.

class Karana.Core.CppWeakRefBase(base: Base)

__call__() → Base | None

Return a the base if it exists, None otherwise.

__deepcopy__(arg0: Any) → CppWeakRefBase

class Karana.Core.DebugManager

all_destroyed_verbosity: ClassVar[int] = 10

enable_locking_trace: ClassVar[bool] = False

static getUsageTrackingErrors() → bool

Get the value of usage tracking errors.

Usage tracking errors is used to enable/disable error messages when discarding variables. If true, it will print errors if the variable if still in use. If false, it will only print a warning, but will continue on anyway.

Returns:

Whether usage tracking errors is enabled or disabled.

static setUsageTrackingErrors(enable: bool) → None

Set the value of usage tracking errors.

Usage tracking errors is used to enable/disable error messages when discarding variables. If true, it will print errors if the variable if still in use. If false, it will only print a warning, but will continue on anyway.

Parameters:

enable – If true, then enable usage tracking errors. If false, then disable it.

class Karana.Core.DumpOptionsBase

id: bool

type_string: bool

class Karana.Core.DumpOptionsLockingBase

Bases: DumpOptionsBase

downstream_deps: bool

healthy_status: bool

id: bool

ref_count: bool

typeString: bool

upstream_deps: bool

class Karana.Core.JsonLogger(name: str)

Base class for json loggers. Json log information will come in on the log functions,

and derived classes can do whatever they want with it.

verbosity: LogLevel

log(json: Karana.Core.Json, verbosity: LogLevel) → None

log(json: Karana.Core.Json, verbosity: LogLevel) → None

Log information from a json object.

Parameters:

• json – The json log information.

• verbosity – The verbosity of the log message.

class Karana.Core.LockingBase(name: str)

Bases: Base

Locking version of the Base class. This is the base class but with logic to make it healthy or not healthy. It also contains logic to add/remove dependents.

addDependent(arg0: LockingBase) → None

Add dependent as a dependent of this, which means whenever we call ensureNotHealthy on this, we will call ensureNotHealthy on the dependent first. Similarly, to make the dependent healthy, we must first make this healthy.

Parameters:

dependent – The LockingBase to add as a dependent.

dumpDependencyGraphviz(filename: os.PathLike | str | bytes, terminal: collections.abc.Sequence[LockingBase] = [], downstream_depth: SupportsInt = -1, upstream_depth: SupportsInt = -1) → None

Create a Graphviz dot file representing the dependency graph. :param filename: Output filename. :param terminal: Nodes to be considered as terminal nodes (stop created

graph on current branch if one of these is reached).

Parameters:

• downstream_depth – Max depth for downstream traversal.

• upstream_depth – Max depth for upstream traversal.

dumpDependencyTree(prefix: str = '', depth: SupportsInt = -1, downstream: bool = True) → None

Display the dependency tree for the object. :param prefix: Optional prefix to add to each line. :param depth: Depth to traverse (default -1 means no limit). :param downstream: Whether to show downstream (true) or upstream (false)

dependencies.

dumpString(prefix: str = '', options: DumpOptionsBase = None) → str

Return a formatted string containing information about this object. :param prefix: String prefix to use for formatting. :param options: Dump options (if null, defaults will be used).

Returns:

A string representation of the object.

ensureHealthy() → None

Make sure this object is healthy if it is not already so.

ensureNotHealthy() → bool

Make sure this object is in not healthy state if it is not already so. :returns: bool If true, then everything went as intended. If false, then we

are _within_ensureHealthy. This is used to signal that we need to call ensureHealthy and not be not healthy.

freeze() → None

Freezes the cache to prevent it from becoming not healthy.

isFrozen() → bool

Returns whether the cache is frozen or not. :returns: true if the cache is frozen, false otherwise.

isHealthy() → bool

Check whether this is locked or unlocked. :returns: True if this is locked, false otherwise.

removeDependent(arg0: LockingBase) → None

Remove dependent as a dependent of this. See addDependent for more information on what a dependent is.

Remove dependent as a dependent of this. :param dependent: The LockingBase to remove as a dependent.

unfreeze() → None

Unfreezes the cache to allow it to become not healthy.

class Karana.Core.LogLevel(value: SupportsInt)

Members:

NUM_TRACE

TRACE

DEBUG

INFO

WARN

ERROR

OFF

DEBUG: ClassVar[LogLevel]

ERROR: ClassVar[LogLevel]

INFO: ClassVar[LogLevel]

NUM_TRACE: ClassVar[LogLevel]

OFF: ClassVar[LogLevel]

TRACE: ClassVar[LogLevel]

WARN: ClassVar[LogLevel]

__members__: ClassVar[dict[str, LogLevel]]

__eq__(other: Any) → bool

__getstate__() → int

__hash__() → int

__index__() → int

__int__() → int

__ne__(other: Any) → bool

__repr__() → str

__setstate__(state: SupportsInt) → None

__str__() → str

property name: str

property value: int

class Karana.Core.MsgLogger

static addConsoleLogger(verbosity: LogLevel) → None

Add a console logger. This prints errors to stderr and everything else to stdout.

The stdout logger is called “stdout” and the stderr logger is called “stderr”.

Parameters:

verbosity – The verbosity of the stdout logger.

static addFileLogger(filename: os.PathLike | str | bytes, verbosity: LogLevel) → None

Add a file logger. This adds a logger that will print to the given file.

The name of the logger is the same as the filename.

Parameters:

• filename – The name of the file to log to.

• verbosity – The verbosity of the new file logger.

static addJsonLogger(logger: JsonLogger) → None

Add a json logger.

Parameters:

logger – The json logger to add.

static changeVerbosity(name: str, verbosity: LogLevel) → None

Remove a logger. :param name: The name of the logger to remove.

static removeLogger(name: str) → None

Remove a logger. :param name: The name of the logger to remove.

Karana.Core.allDestroyed(bc: BaseContainer = None) → bool

Checks if all Base objects have been destroyed.

This issues warnings for anything that has not been destroyed.

Parameters:

bc – Pointer to the base container to check. If nullptr is provided (the default), then the BaseContainer::singleton will be used.

Returns:

True if all objects have been destroyed, false otherwise.

Karana.Core.allHealthy(bc: BaseContainer = None) → bool

Checks whether all non-DataCache objects are healthy

Parameters:

bc – Pointer to the base container whose LockingBases you want to check. If nullptr is provided (the default), then the BaseContainer::singleton will be used.

Returns:

True if all objects are healthy

Karana.Core.allReady(bc: BaseContainer = None) → bool

Checks is the params for all the Base objects in the provided

BaseContainer are ready.

Parameters:

bc – Pointer to the base container to check. If nullptr is provided (the default), then the BaseContainer::singleton will be used.

Returns:

true if the all the Bases are ready, false otherwise.

Karana.Core.debug(msg: str) → None

Karana.Core.debug(f: collections.abc.Callable[[], str]) → None

Write an debug to all loggers using a function that outputs a message.

This function is only executed if one or more sinks will consume it.

Parameters:

f – The function that generates the debug message

Karana.Core.debugJson(json: Karana.Core.Json) → None

Karana.Core.debugJson(json: Karana.Core.Json, fn: collections.abc.Callable[[Karana.Core.Json], str]) → None

Write an debug to all loggers using the provided ordered json and json_to_string

function.

Parameters:

• json – The ordered json debug information.

• fn – The function that generates a string from the provided ordered json.

Karana.Core.discard(base: Base) → None

Karana.Core.discard(bases: collections.abc.Sequence[Base]) → None

Discard a sequence of Bases.

Parameters:

bases (collections.abc.Sequence[Base]) – The sequence of bases to discard.

Karana.Core.error(msg: str) → None

Karana.Core.error(f: collections.abc.Callable[[], str]) → None

Write an error to all loggers using a function that outputs a message.

This function is only executed if one or more sinks will consume it.

Parameters:

f – The function that generates the error message

Karana.Core.findShareDir() → pathlib.Path

Find the /share/Karana path on the system respecting the KARANA_SHARE_DIR environment variable override.

Returns:

The /share/Karana path

Karana.Core.info(msg: str) → None

Karana.Core.info(f: collections.abc.Callable[[], str]) → None

Write an info to all loggers using a function that outputs a message.

This function is only executed if one or more sinks will consume it.

Parameters:

f – The function that generates the info message

Karana.Core.numTrace(msg: str) → None

Karana.Core.numTrace(f: collections.abc.Callable[[], str]) → None

Write an num_trace to all loggers using a function that outputs a message.

This function is only executed if one or more sinks will consume it. This will only run in debug mode. If NDEBUG is defined, it is a no-op.

Parameters:

f – The function that generates the num_trace message

Karana.Core.trace(msg: str) → None

Karana.Core.trace(f: collections.abc.Callable[[], str]) → None

Write an trace to all loggers using a function that outputs a message.

This function is only executed if one or more sinks will consume it.

Parameters:

f – The function that generates the trace message

Karana.Core.traceJson(json: Karana.Core.Json) → None

Karana.Core.traceJson(json: Karana.Core.Json, fn: collections.abc.Callable[[Karana.Core.Json], str]) → None

Write an trace to all loggers using the provided ordered json and json_to_string

function.

Parameters:

• json – The ordered_json trace information.

• fn – A function that generates a string from the provided ordered json.

Karana.Core.warn(msg: str) → None

Karana.Core.warn(f: collections.abc.Callable[[], str]) → None

Write an warn to all loggers using a function that outputs a message.

This function is only executed if one or more sinks will consume it.

Parameters:

f – The function that generates the warn message