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	Base class used for Var and BaseWithVars.
BaseContainer	Container class that holds all the Base objects.
BaseVars	Common base class used by most simulation objects.
BaseWithVars
CppWeakRefBase
DebugManager
DisableBaseContainerWrites	RAII class that disables base container writes in a context.
DumpOptionsBase
DumpOptionsBaseWithVars
DumpOptionsLockingBase
IdGenerator
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
LockingBaseVars	The Vars for the LockingBase class.
LogLevel	Enum that keeps track of the verbosity levels.
MsgLogger
NestedVars	A structure to hold nested Vars.
ResourceFinder
ThreadPool
Var	Base class for all Vars.
VarBool	Base class for all Vars.
VarChar	Base class for all Vars.
VarDouble	Base class for all Vars.
VarFloat	Base class for all Vars.
VarHomTran	Base class for all Vars.
VarId	Base class for all Vars.
VarInt	Base class for all Vars.
VarLong	Base class for all Vars.
VarMat	Base class for all Vars.
VarMat33	Base class for all Vars.
VarMat66	Base class for all Vars.
VarShort	Base class for all Vars.
VarSpatialAcceleration	Base class for all Vars.
VarSpatialForce	Base class for all Vars.
VarSpatialVector	Base class for all Vars.
VarSpatialVelocity	Base class for all Vars.
VarString	Base class for all Vars.
VarType	Enums for the Var type.
VarUnitQuaternion	Base class for all Vars.
VarVec	Base class for all Vars.
VarVec3	Base class for all Vars.
VarVec4	Base class for all Vars.
VarVec6	Base class for all Vars.
VarVecInt	Base class for all Vars.
VarVecString	Base class for all Vars.
VoidCallbackRegistry

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)

Base class used for Var and BaseWithVars.

Most simulation objects will derive from BaseWithVars.

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.

rename(arg0: str) → None

Rename this object.

Parameters:

new_name – New name for this object.

typeString(brief: bool = True) → str

Returns the type string of Base.

Parameters:

brief – if true, return the short form of the class type name, else the full type name

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.

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 | SupportsIndex) → 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 | SupportsIndex) → LockingBase | None

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

contains(arg0: SupportsInt | SupportsIndex) → 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.

disableWrites() → DisableBaseContainerWrites

Disables inserting or erasing items from this BaseContainer.

Returns:

An RAII class that disables writing (inserting or erasing) items to/from this BaseContainer while the DisableBaseContainerWrites is in scope.

property at_exit_fns: VoidCallbackRegistry

class Karana.Core.BaseVars

Common base class used by most simulation objects.

static create() → BaseVars

Create a new instance of BaseVars.

Parameters:

bwv – The BaseWithVars that this BaseVars will be associated with.

Returns:

A pointer to the newly created instance of BaseVars.

dump(prefix: str = '', depth: SupportsInt | SupportsIndex = 0) → None

Dump all of the Vars to stdout.

Parameters:

• prefix – The prefix to put in front of each Var.

• depth – How many levels deep to dump. A negative value will dump all levels.

dumpString(prefix: str = '', depth: SupportsInt | SupportsIndex = 0) → str

Dump all of the Vars as a string.

Parameters:

• prefix – The prefix to put in front of each Var.

• depth – How many levels deep to dump. A negative value will dump all levels.

Returns:

A string with the information about all the Vars contained within.

getAllVars() → NestedVars

Get all the Vars that this BaseVars has.

Returns:

A map of Vars, where the Var name is the key and the Var is the value.

class Karana.Core.BaseWithVars(name: str)

Bases: Base

static create(name: str) → BaseWithVars

Create an instance of BaseWithVars

Parameters:

name – Name for the BaseWithVars class.

Returns:

A pointer to the newly created BaseWithVars class.

getVars() → BaseVars

Get the vars for this object.

Returns:

The vars for this object.

class Karana.Core.CppWeakRefBase(base: Base)

__call__() → Base | None

Return a the base if it exists, None otherwise.

__deepcopy__(arg0: Any) → CppWeakRefBase

useCount() → None

Print the use count of the object.

class Karana.Core.DebugManager

all_destroyed_message_limit: ClassVar[int] = 10

enable_locking_trace: ClassVar[bool] = False

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

Create a Graphviz dot file representing the dependency graph.

Parameters:

• locking_base – The LockingBase to display the dependency graph for.

• filename – Output filename.

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

• downstream_depth – Max depth for downstream traversal.

• upstream_depth – Max depth for upstream traversal.

static dumpDependencyTree(locking_base: LockingBase, prefix: str = '', depth: SupportsInt | SupportsIndex = -1, downstream: bool = True) → None

Display the dependency tree for the provided LockingBase.

Parameters:

• locking_base – The LockingBase to display the dependency tree for.

• prefix – Optional prefix to add to each line.

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

• downstream – Whether to show downstream (true) or upstream (false) dependencies.

static dumpInUseBy(arg0: Base) → None

Display the list of Base objects that are using this one.

Parameters:

base – Base object to dump users of.

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 inUseBy(arg0: Base) → list[Base]

Return the list of Base objects that are using the provided one.

The list includes objects that are referring to this object, but not ones that will remove the reference if this object were discarded. The purpose of this method is to catch commonly occurring dependencies that will get in the way of discarding this object.

Parameters:

base – The object to get the list of objects that depend upon it.

Returns:

List of objects that depend on this one.

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.DisableBaseContainerWrites(container: BaseContainer | None = None)

RAII class that disables base container writes in a context.

__enter__() → DisableBaseContainerWrites

__exit__(arg0: type | None, arg1: Any | None, arg2: Any | None) → bool

close() → None

Enable writes for the provided container again.

class Karana.Core.DumpOptionsBase

cache_deps: bool

id: bool

ref_count: bool

type_string: bool

class Karana.Core.DumpOptionsBaseWithVars

Bases: DumpOptionsBase

vars: bool

property vars_depth: int

class Karana.Core.DumpOptionsLockingBase

Bases: DumpOptionsBaseWithVars

downstream_deps: bool

healthy_status: bool

id: bool

upstream_deps: bool

class Karana.Core.IdGenerator

static singleton() → IdGenerator

Get the singleton instance of IdGenerator.

Returns:

The singleton instance of IdGenerator.

generate() → int

Generate a new id.

Returns:

The newly generated id.

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: BaseWithVars

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.

static create(name: str) → LockingBase

LockingBase class constructor.

Parameters:

name – Name for the base class.

Returns:

A pointer to the newly created LockingBase.

addDependent(dependent: 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.

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

Return a formatted string containing information about this object.

Parameters:

• prefix – String prefix to use for formatting.

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

getVars() → LockingBaseVars

Get the vars for this object.

Returns:

The vars for this object.

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 healthy or not.

Returns:

True if this is healthy, false otherwise.

removeDependent(dependent: 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.

Parameters:

dependent – The LockingBase to remove as a dependent.

unfreeze() → None

Unfreezes the cache to allow it to become not healthy.

class Karana.Core.LockingBaseVars

Bases: BaseVars

The Vars for the LockingBase class.

property downstream_deps: VarVecString

The downstream dependencies

property healthy: VarBool

The health status

property ref_count: VarInt

The reference count

property upstream_deps: VarVecString

The upstream dependencies

class Karana.Core.LogLevel

Bases: enum.IntEnum

Enum that keeps track of the verbosity levels.

DEBUG: ClassVar[LogLevel]

ERROR: ClassVar[LogLevel]

INFO: ClassVar[LogLevel]

NUM_TRACE: ClassVar[LogLevel]

OFF: ClassVar[LogLevel]

TRACE: ClassVar[LogLevel]

WARN: ClassVar[LogLevel]

__format__(format_spec)

Convert to a string according to format_spec.

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

Change the verbosity of a logger.

Parameters:

• name – The name of the logger whose verbosity you want to change.

• verbosity – The new verbosity of the logger.

static getVerbosity(name: str) → LogLevel

Get the verbosity of a logger.

Parameters:

name – The name of the logger whose verbosity you want to get.

Returns:

The verbosity of the provided logger.

static removeLogger(name: str) → None

Remove a logger.

Parameters:

name – The name of the logger to remove.

class Karana.Core.NestedVars

A structure to hold nested Vars.

property description: str

Description for the NestedVars

property local_vars: list[Var]

Local vars at the current level

property name: str

Name of the NestedVars

property nested_vars: list[NestedVars]

Nested Vars

class Karana.Core.ResourceFinder

static singleton() → ResourceFinder

Get the global ResourceFinder instance

Returns:

The ResourceFinder

appendSearchPath(path: os.PathLike | str | bytes) → None

Add a low priority search path to the end of the list

Parameters:

path – The path to add

getSearchPaths() → list[pathlib.Path]

Get the list of search paths in descending priority

Returns:

The search paths

prependSearchPath(path: os.PathLike | str | bytes) → None

Add a high priority search path to the start of the list

Parameters:

path – The path to add

resolve(path: os.PathLike | str | bytes) → pathlib.Path

Find the given file.

If the given path is absolute, it is used verbatim without any searching as long as the path exists.

If the path is relative, this function checks relative to a configured list of search paths, returning the absolute path of the first existing file that is found.

The search paths are a list of filepaths in descending order of priority. First, the current directory is considered, followed by a list determined by the KARANA_RESOURCE_PATH environment variable, which should be a list of filepaths, separated by operating system’s standard delimiter (‘:’ on macos or linux, ‘;’ on windows). The search paths may further be modified at runtime using the methods of this class.

If no exiting file can be found, an error will be thrown.

Parameters:

path – The filepath to search for.

Returns:

The resolved, existing absolute path.

setSearchPaths(paths: collections.abc.Sequence[os.PathLike | str | bytes]) → None

Overwrite the list of search paths in descending priority

Parameters:

paths – The new search paths

shorten(path: os.PathLike | str | bytes) → pathlib.Path

Convert a resolved path back to a relative path.

Given a potentially absolute path within one of the search paths, find the shortest equivalent relative path that can be resolved. If the path cannot be shortened, returns the given path unchanged.

Parameters:

path – A resolved absolute filepath.

Returns:

The shortened path relative to a search path or the given path if no matching search path is found.

class Karana.Core.ThreadPool

static singleton() → ThreadPool

Get the global ThreadPool instance

Returns:

The ThreadPool

addPriorityTask(task: collections.abc.Callable[[], None]) → None

Add task to the front of the queue.

Parameters:

task – The task to be completed.

addTask(task: collections.abc.Callable[[], None]) → None

Add task to the back of the queue.

Parameters:

task – The task to be completed.

getThreadPoolSize() → int

Get the number of workers in the thread pool.

Returns:

The number of workers in the thread pool.

setThreadPoolSize(num_threads: SupportsInt | SupportsIndex) → None

Set the number of worker threads in the pool.

Parameters:

num_threads – The size of the thread pool.

class Karana.Core.Var(name: str)

Bases: Base

Base class for all Vars.

description() → str

Description of this Var.

Returns:

Description of this Var.

getType() → VarType

Get the VarType for this Var.

Returns:

The VarType for this Var.

quantity() → str

Quantity type of this Var.

Returns:

Quantity type of this Var.

class Karana.Core.VarBool(name: str, fn: collections.abc.Callable[[], bool], description: str, quantity: str = '')

class Karana.Core.VarBool(name: str, other: VarBool, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], bool], description: str, quantity: str = '') → VarBool

static create(name: str, other: VarBool, description: str) → VarBool

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → bool

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarChar(name: str, fn: collections.abc.Callable[[], str], description: str, quantity: str = '')

class Karana.Core.VarChar(name: str, other: VarChar, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], str], description: str, quantity: str = '') → VarChar

static create(name: str, other: VarChar, description: str) → VarChar

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → str

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarDouble(name: str, fn: collections.abc.Callable[[], float], description: str, quantity: str = '')

class Karana.Core.VarDouble(name: str, other: VarDouble, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], float], description: str, quantity: str = '') → VarDouble

static create(name: str, other: VarDouble, description: str) → VarDouble

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → float

Return the value that the Var contains.

Returns:

The value that the Var contains.

getPlottingFunction() → collections.abc.Callable[[], float]

Return the plotting function associated with this Var.

Returns:

The plotting function associated with this Var.

class Karana.Core.VarFloat(name: str, fn: collections.abc.Callable[[], float], description: str, quantity: str = '')

class Karana.Core.VarFloat(name: str, other: VarFloat, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], float], description: str, quantity: str = '') → VarFloat

static create(name: str, other: VarFloat, description: str) → VarFloat

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → float

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarHomTran(name: str, fn: collections.abc.Callable[[], Karana.Math.HomTran], description: str, quantity: str = '')

class Karana.Core.VarHomTran(name: str, other: VarHomTran, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Karana.Math.HomTran], description: str, quantity: str = '') → VarHomTran

static create(name: str, other: VarHomTran, description: str) → VarHomTran

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Karana.Math.HomTran

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarId(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '')

class Karana.Core.VarId(name: str, other: VarId, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '') → VarId

static create(name: str, other: VarId, description: str) → VarId

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → int

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarInt(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '')

class Karana.Core.VarInt(name: str, other: VarInt, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '') → VarInt

static create(name: str, other: VarInt, description: str) → VarInt

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → int

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarLong(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '')

class Karana.Core.VarLong(name: str, other: VarLong, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '') → VarLong

static create(name: str, other: VarLong, description: str) → VarLong

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → int

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarMat(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [m, n]]], matrix_rows: SupportsInt | SupportsIndex, matrix_cols: SupportsInt | SupportsIndex, description: str, quantity: str = '')

class Karana.Core.VarMat(name: str, other: VarMat, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [m, n]]], matrix_rows: SupportsInt | SupportsIndex, matrix_cols: SupportsInt | SupportsIndex, description: str, quantity: str = '') → VarMat

static create(name: str, other: VarMat, description: str) → VarMat

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.float64], [m, n]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarMat33(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 3]]], description: str, quantity: str = '')

class Karana.Core.VarMat33(name: str, other: VarMat33, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 3]]], description: str, quantity: str = '') → VarMat33

static create(name: str, other: VarMat33, description: str) → VarMat33

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.float64], [3, 3]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarMat66(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [6, 6]]], description: str, quantity: str = '')

class Karana.Core.VarMat66(name: str, other: VarMat66, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [6, 6]]], description: str, quantity: str = '') → VarMat66

static create(name: str, other: VarMat66, description: str) → VarMat66

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.float64], [6, 6]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarShort(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '')

class Karana.Core.VarShort(name: str, other: VarShort, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], int], description: str, quantity: str = '') → VarShort

static create(name: str, other: VarShort, description: str) → VarShort

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → int

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarSpatialAcceleration(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialAcceleration], description: str, quantity: str = '')

class Karana.Core.VarSpatialAcceleration(name: str, other: VarSpatialAcceleration, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialAcceleration], description: str, quantity: str = '') → VarSpatialAcceleration

static create(name: str, other: VarSpatialAcceleration, description: str) → VarSpatialAcceleration

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Karana.Math.SpatialAcceleration

Return the value that the Var contains.

Returns:

The value that the Var contains.

getPlottingFunction() → collections.abc.Callable[[], Karana.Math.SpatialAcceleration]

Return the plotting function associated with this Var.

Returns:

The plotting function associated with this Var.

class Karana.Core.VarSpatialForce(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialForce], description: str, quantity: str = '')

class Karana.Core.VarSpatialForce(name: str, other: VarSpatialForce, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialForce], description: str, quantity: str = '') → VarSpatialForce

static create(name: str, other: VarSpatialForce, description: str) → VarSpatialForce

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Karana.Math.SpatialForce

Return the value that the Var contains.

Returns:

The value that the Var contains.

getPlottingFunction() → collections.abc.Callable[[], Karana.Math.SpatialForce]

Return the plotting function associated with this Var.

Returns:

The plotting function associated with this Var.

class Karana.Core.VarSpatialVector(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialVector], description: str, quantity: str = '')

class Karana.Core.VarSpatialVector(name: str, other: VarSpatialVector, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialVector], description: str, quantity: str = '') → VarSpatialVector

static create(name: str, other: VarSpatialVector, description: str) → VarSpatialVector

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Karana.Math.SpatialVector

Return the value that the Var contains.

Returns:

The value that the Var contains.

getPlottingFunction() → collections.abc.Callable[[], Karana.Math.SpatialVector]

Return the plotting function associated with this Var.

Returns:

The plotting function associated with this Var.

class Karana.Core.VarSpatialVelocity(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialVelocity], description: str, quantity: str = '')

class Karana.Core.VarSpatialVelocity(name: str, other: VarSpatialVelocity, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Karana.Math.SpatialVelocity], description: str, quantity: str = '') → VarSpatialVelocity

static create(name: str, other: VarSpatialVelocity, description: str) → VarSpatialVelocity

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Karana.Math.SpatialVelocity

Return the value that the Var contains.

Returns:

The value that the Var contains.

getPlottingFunction() → collections.abc.Callable[[], Karana.Math.SpatialVelocity]

Return the plotting function associated with this Var.

Returns:

The plotting function associated with this Var.

class Karana.Core.VarString(name: str, fn: collections.abc.Callable[[], str], description: str, quantity: str = '')

class Karana.Core.VarString(name: str, other: VarString, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], str], description: str, quantity: str = '') → VarString

static create(name: str, other: VarString, description: str) → VarString

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → str

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarType(*args, **kwds)

Bases: enum.Enum

Enums for the Var type.

BASEVARS: ClassVar[VarType]

CHAR: ClassVar[VarType]

DOUBLE: ClassVar[VarType]

FLOAT: ClassVar[VarType]

INT: ClassVar[VarType]

LONG: ClassVar[VarType]

MAT: ClassVar[VarType]

MAT33: ClassVar[VarType]

MAT66: ClassVar[VarType]

SHORT: ClassVar[VarType]

STRING: ClassVar[VarType]

VEC: ClassVar[VarType]

VEC3: ClassVar[VarType]

VEC6: ClassVar[VarType]

VEC_INT: ClassVar[VarType]

class Karana.Core.VarUnitQuaternion(name: str, fn: collections.abc.Callable[[], Karana.Math.UnitQuaternion], description: str, quantity: str = '')

class Karana.Core.VarUnitQuaternion(name: str, other: VarUnitQuaternion, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Karana.Math.UnitQuaternion], description: str, quantity: str = '') → VarUnitQuaternion

static create(name: str, other: VarUnitQuaternion, description: str) → VarUnitQuaternion

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Karana.Math.UnitQuaternion

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarVec(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]], vector_size: SupportsInt | SupportsIndex, description: str, quantity: str = '')

class Karana.Core.VarVec(name: str, other: VarVec, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]], vector_size: SupportsInt | SupportsIndex, description: str, quantity: str = '') → VarVec

static create(name: str, other: VarVec, description: str) → VarVec

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

getPlottingFunction() → collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [m, 1]]]

Return the plotting function associated with this Var.

Returns:

The plotting function associated with this Var.

class Karana.Core.VarVec3(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]], description: str, quantity: str = '')

class Karana.Core.VarVec3(name: str, other: VarVec3, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]], description: str, quantity: str = '') → VarVec3

static create(name: str, other: VarVec3, description: str) → VarVec3

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

getPlottingFunction() → collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]]

Return the plotting function associated with this Var.

Returns:

The plotting function associated with this Var.

class Karana.Core.VarVec4(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [4, 1]]], description: str, quantity: str = '')

class Karana.Core.VarVec4(name: str, other: VarVec4, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [4, 1]]], description: str, quantity: str = '') → VarVec4

static create(name: str, other: VarVec4, description: str) → VarVec4

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.float64], [4, 1]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarVec6(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [6, 1]]], description: str, quantity: str = '')

class Karana.Core.VarVec6(name: str, other: VarVec6, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [6, 1]]], description: str, quantity: str = '') → VarVec6

static create(name: str, other: VarVec6, description: str) → VarVec6

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.float64], [6, 1]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarVecInt(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.int32], [m, 1]]], vector_size: SupportsInt | SupportsIndex, description: str, quantity: str = '')

class Karana.Core.VarVecInt(name: str, other: VarVecInt, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.int32], [m, 1]]], vector_size: SupportsInt | SupportsIndex, description: str, quantity: str = '') → VarVecInt

static create(name: str, other: VarVecInt, description: str) → VarVecInt

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → Annotated[numpy.typing.NDArray[numpy.int32], [m, 1]]

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VarVecString(name: str, fn: collections.abc.Callable[[], list[str]], description: str, quantity: str = '')

class Karana.Core.VarVecString(name: str, other: VarVecString, description: str)

Bases: Var

Base class for all Vars.

static create(name: str, fn: collections.abc.Callable[[], list[str]], description: str, quantity: str = '') → VarVecString

static create(name: str, other: VarVecString, description: str) → VarVecString

Rename Var_T constructor.

This constructor keeps the same function, size, etc., but takes a new name and description.

Parameters:

• name – The name of the Var_T<T>

• other – The Var_T<T> to copy the callable and quantity from.

• description – A description of the Var.

Returns:

The newly created instance of Var_T<T>.

__call__() → list[str]

Return the value that the Var contains.

Returns:

The value that the Var contains.

class Karana.Core.VoidCallbackRegistry

trace_callback_registry: bool

__contains__(arg0: str) → bool

Check whether the given callback is contained within the registry. :param item: The name of the callback to check for. :type item: str

Returns:

True if the item is in the CallbackRegistry, False otherwise.

Return type:

bool

__getitem__(key: str | SupportsInt | SupportsIndex) → collections.abc.Callable[[], None]

Get a function by name

__len__() → int

Get the number of callbacks registered to the CallbackRegistry.

Returns:

Number of callbacks registered in the CallbackRegistry.

Return type:

int

__setitem__(key: str | SupportsInt | SupportsIndex, func: collections.abc.Callable[[], None]) → None

Set a function with a string name or integer index

addDependency(parent: str, child: str) → None

addDependency(parent: SupportsInt | SupportsIndex, child: SupportsInt | SupportsIndex) → None

Add a dependency to the the execution graph. :param parent: The index of the callback that must finish first. :type parent: int :param child: The index of the callback that waits for the parent. :type child: int

clear() → None

Clear out the entire CallbackRegistry. All callbacks will be removed.

dump(prefix: str = '') → None

Print out the string from dumpString. See dumpString for more details.

dumpString(prefix: str = '') → str

Create a string that lists all the functions by name.

erase(name: str, okay_not_exists: bool = False) → None

erase(index: SupportsInt | SupportsIndex) → None

Erase the callback at the provided index.

Parameters:

name (int) – The index of the callback to erase.

execute() → None

Execute all functions in the registry.

executeAndPopReverse() → None

Execute all functions in the registry in reverse and delete them as we go.

executeReverse() → None

Execute all functions in the registry in reverse.

getDependencies(index: SupportsInt | SupportsIndex) → list[int]

getDependencies(name: str) → list[int]

Remove all dependencies from the given callback.

The dependencies are the parent edges in the DAG that this callback depends on before it can execute.

Parameters:

name (str) – The name of the callback to get dependencies for.

getDependents(index: SupportsInt | SupportsIndex) → list[int]

getDependents(name: str) → list[int]

Remove all dependents from the given callback.

The dependents are the children in the DAG that depend on this callback completing before they can run.

Parameters:

name (str) – The name of the callback to get dependents for.

insertAfter(item: str, name: str, fn: collections.abc.Callable[[], None]) → None

insertAfter(index: SupportsInt | SupportsIndex, name: str, fn: collections.abc.Callable[[], None]) → None

Insert a function after another in the registry. :param index: The index to insert this item after. :type index: int :param name: The name of the new item. :type name: str :param fn: The callback associated with the new item. :type fn: Callable

insertBefore(item: str, name: str, fn: collections.abc.Callable[[], None]) → None

insertBefore(index: SupportsInt | SupportsIndex, name: str, fn: collections.abc.Callable[[], None]) → None

Insert a function before another in the registry. :param index: The index to insert this item before. :type index: int :param name: The name of the new item. :type name: str :param fn: The callback associated with the new item. :type fn: Callable

pop(name: str) → collections.abc.Callable[[], None]

pop(index: SupportsInt | SupportsIndex) → collections.abc.Callable[[], None]

Pop the callback at the provided index.

Parameters:

name (int) – The index of the callback to pop.

removeAllDependencies() → None

removeAllDependencies(index: SupportsInt | SupportsIndex) → None

removeAllDependencies(name: str) → None

Remove all dependencies from the given callback.

The dependencies are the parent edges in the DAG that this callback depends on before it can execute.

Parameters:

name (str) – The index of the callback to remove all dependencies from.

removeAllDependents(index: SupportsInt | SupportsIndex) → None

removeAllDependents(name: str) → None

Remove all dependents from the given callback.

The dependents are the children edges in the DAG that depend on this callback executing before they can execute.

Parameters:

name (str) – The index of the callback to remove all dependents from.

removeDependency(parent: str, child: str) → None

removeDependency(parent: SupportsInt | SupportsIndex, child: SupportsInt | SupportsIndex) → None

Remove a dependency from the the execution graph. :param parent: The index of the callback that must finish first. :type parent: int :param child: The index of the callback that waits for the parent. :type child: int

runInParallel(indices: collections.abc.Sequence[SupportsInt | SupportsIndex]) → None

runInParallel(names: collections.abc.Sequence[str]) → None

This runs the given callbacks in parallel.

This modifies the DAG as follows: 1. A “base” callback is found. This is the callback with the shallowest depth in the DAG. If more than one callback has the same depth, then the callback with

the lowest index is used.

2. All the callbacks associated with the given indices are modified to have the same parents/children as the base.

3. The callbacks whose edges were modified have their previous parents tied to their previous children.

Parameters:

names (list[str]) – The names of the callbacks to run in parallel.

size() → int

Get the number of callbacks registered to the CallbackRegistry.

Returns:

Number of callbacks registered in the CallbackRegistry.

Return type:

int

transitiveReduction() → None

Perform transitive reduction on the callbacks DAG. This preserves the reachability between all callbacks in the DAG while removing all redundant, transitive edges

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