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	@class Base Common base class used by most simulation objects.
BaseContainer	Container class that holds all the Base objects.
CppWeakRefBase
DebugManager
DumpOptionsBase
DumpOptionsLockingBase
JsonLogger	@class JsonLogger Base class for json loggers. Json log information
LockingBase	@class LockingBase Locking version of the Base class. This is the base
LogLevel	Members:
MsgLogger

Functions

deprecated(…)	Use this decorator is used to mark functions or classes as deprecated.
allCurrent(→ bool)	Checks whether all non-DataCache objects are current
allDestroyed(→ bool)	Checks if all Base objects have been destroyed. This issues warnings
allFinalized(→ 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.
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)

@class Base Common base class used by most simulation objects.

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

Print dumpString on std::cout.

Parameter prefix:

A string to use as prefix for each output line

Parameter options:

Struct with options to tailor the output

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

Return information about the object.

Parameter prefix:

A string to use as prefix for each output line

Parameter 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.

isFinalized() → 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.

Parameter 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.

Parameter 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.

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.

Parameter 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

current_status: bool

downstream_deps: bool

id: bool

ref_count: bool

typeString: bool

upstream_deps: bool

class Karana.Core.JsonLogger(name: str)

@class JsonLogger 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.

Parameter json:

The json log information.

Parameter verbosity:

The verbosity of the log message.

class Karana.Core.LockingBase(name: str)

Bases: Base

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

addDependent(arg0: LockingBase) → None

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

Parameter 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.

Parameter filename:

Output filename.

Parameter terminal:

Nodes to be considered as terminal nodes (stop created graph on current branch if one of these is reached).

Parameter downstream_depth:

Max depth for downstream traversal.

Parameter upstream_depth:

Max depth for upstream traversal.

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

Display the dependency tree for the object.

Parameter prefix:

Optional prefix to add to each line.

Parameter depth:

Depth to traverse (default -1 means no limit).

Parameter 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.

Parameter prefix:

String prefix to use for formatting.

Parameter options:

Dump options (if null, defaults will be used).

Returns:

A string representation of the object.

ensureCurrent() → None

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

ensureStale() → bool

Make sure this object is in stale state if it is not already so.

Returns:

bool If true, then everything went as intended. If false, then we are _within_ensureCurrent. This is used to signal that we need to call ensureCurrent and not be stale.

freeze() → None

Freezes the cache to prevent it from becoming stale.

isCurrent() → bool

Check whether this is locked or unlocked.

Returns:

True if this is locked, false otherwise.

isFrozen() → bool

Returns whether the cache is frozen or not.

Returns:

true if the cache is frozen, 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.

Parameter dependent:

The LockingBase to remove as a dependent.

unfreeze() → None

Unfreezes the cache to allow it to become stale.

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”.

Parameter 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.

Parameter filename:

The name of the file to log to.

Parameter verbosity:

The verbosity of the new file logger.

static addJsonLogger(logger: JsonLogger) → None

Add a json logger.

Parameter logger:

The json logger to add.

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

Remove a logger.

Parameter name:

The name of the logger to remove.

static removeLogger(name: str) → None

Remove a logger.

Parameter name:

The name of the logger to remove.

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

Checks whether all non-DataCache objects are current

Parameter 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 current

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.

Parameter 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.allFinalized(bc: BaseContainer = None) → bool

Checks is the params for all the Base objects in the provided BaseContainer have been finalized.

Parameter 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 have been finalized, 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.

Parameter 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.

Parameter json:

The ordered json debug information.

Parameter 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.

Parameter f:

The function that generates the error message

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.

Parameter 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.

Parameter 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.

Parameter 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.

Parameter json:

The ordered_json trace information.

Parameter 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.

Parameter f:

The function that generates the warn message