Karana.KUtils.BasicPrefab

BasicPrefab and associated classes.

This Prefab is used to generically represent multibody objects and a list of KModels.

Attributes

LinkJointTree
ExtraInfoType

Classes

BasicParams	Params for the BasicPrefab.
BasicContext	Context for the BasicPrefab.
BasicPrefab	BasicPrefab for holding multibody objects and KModels.
BasicPrefabDS	A DataStruct representation of a BasicPrefab.

Functions

getUid(→ int)	Get a unique ID.
urdfToBodyDS(...)	Convert from a urchin Link and Joint to a BodyDS.
urdfToBodyWithContextDS(...)	Convert from links and joints to BodyWithContextDS.
readUrdf(→ BasicPrefabDS[ExtraInfoType])	Read a URDF file and convert it to a name and list of BodyWithContextDS.
bodyDSToUrdf(→ tuple[urchin.Link, urchin.Joint])	Convert the BodyDS to a urchin Link and Joint. These can be used to create a URDF file.
bodyWithContextDSToUrdf(→ tuple[list[urchin.Link], ...)	Convert a BodyWithContextDS to a list of Links and Joints. These can be used to create a URDF file.
writeUrdf(basic_prefab_ds, file)	Convert this DataStruct to a URDF file.

Module Contents

type Karana.KUtils.BasicPrefab.LinkJointTree = list[tuple[Link, Joint, 'LinkJointTree']]

Karana.KUtils.BasicPrefab.ExtraInfoType

Karana.KUtils.BasicPrefab.getUid() → int

Get a unique ID.

This is used by the URDF writer to get unique IDs that can be used to associate subhinges with SubhingeSpringDamper KModels.

Returns:

A unique ID.

Return type:

int

Karana.KUtils.BasicPrefab.urdfToBodyDS(link: urchin.Link, joint: urchin.Joint) → tuple[Karana.Dynamics.SOADyn_types.BodyDS, Karana.Models.GeneralKModels_types.SubhingeSpringDamperDS | None]

Convert from a urchin Link and Joint to a BodyDS.

Parameters:

• link (Link) – The URDF Link.

• joint (Joint) – The URDF parent joint.

Returns:

The BodyDS representation of the provided Link/Joint pair and any SubhingeSpringDamperDS representations of joint damping.

Return type:

tuple[BodyDS, list[SubhingeSpringDamperDS]]

Karana.KUtils.BasicPrefab.urdfToBodyWithContextDS(link: urchin.Link, joint: urchin.Joint, children_urdf: LinkJointTree) → tuple[Karana.Dynamics.SOADyn_types.BodyWithContextDS, list[Karana.Models.GeneralKModels_types.SubhingeSpringDamperDS]]

Convert from links and joints to BodyWithContextDS.

Parameters:

• link (Link) – The link to use for creating the body.

• joint (Joint) – The joint to use for creating the body.

• children_urdf (LinkJointTree) – A LinkJointTree that defines the links and joints to use for the children. This is an arbitrarily nested list of tuples of links and joints, each of which can be used to define a body.

Returns:

The BodyWithContextDS representation of the provided Links/Joints and any SubhingeSpringDamperDS representations of joint damping for the provided Joints.

Return type:

tuple[BodyWithContextDS, list[SubhingeSpringDamperDS]]

Karana.KUtils.BasicPrefab.readUrdf(file: pathlib.Path | str) → BasicPrefabDS[ExtraInfoType]

Read a URDF file and convert it to a name and list of BodyWithContextDS.

Parameters:

file (Path | str) – The file to read the URDF from.

Returns:

A SubTreeDS representing the URDF file.

Return type:

SubTreeDS

Karana.KUtils.BasicPrefab.bodyDSToUrdf(body_ds: Karana.Dynamics.SOADyn_types.BodyDS, parent_link: str, models: list[Karana.Models.GeneralKModels_types.SubhingeSpringDamperDS]) → tuple[urchin.Link, urchin.Joint]

Convert the BodyDS to a urchin Link and Joint. These can be used to create a URDF file.

Parameters:

parent_link (str) – The name of the parent link for the Joint.

Returns:

The Link and Joint associated with this body.

Return type:

tuple[Link, Joint]

Karana.KUtils.BasicPrefab.bodyWithContextDSToUrdf(body_with_context_ds: Karana.Dynamics.SOADyn_types.BodyWithContextDS, parent_link: str, models: list[Karana.Models.GeneralKModels_types.SubhingeSpringDamperDS]) → tuple[list[urchin.Link], list[urchin.Joint]]

Convert a BodyWithContextDS to a list of Links and Joints. These can be used to create a URDF file.

Parameters:

• body_with_context_ds (BodyWithContextDS) – The BodyWithContextDS to convert to a list of URDF links and joints.

• parent_link (str) – The name of the parent link for the body of this BodyWithContextDS.

Returns:

The Links and Joints associated with the body and children of this BodyWithContextDS.

Return type:

tuple[list[Link], list[Joint]]

Karana.KUtils.BasicPrefab.writeUrdf(basic_prefab_ds: BasicPrefabDS[ExtraInfoType], file: pathlib.Path | str)

Convert this DataStruct to a URDF file.

Parameters:

• basic_prefab_ds (BasicPrefabDS[ExtraInfoType]) – The BasicPrefab DataStruct to convert to a URDF file.

• file (Path | str) – The file to write the URDF to.

class Karana.KUtils.BasicPrefab.BasicParams(/, **data: Any)

Bases: Karana.KUtils.Prefab.Params, Generic[ExtraInfoType]

Params for the BasicPrefab.

Parameters:

• subtree (SubTreeDS[SubTreeDSType]) – The SubTree of bodies/nodes to add.

• models (list[tuple[KModelDS[BaseKModelType], KModelStateDS[BaseKModelType] | None]] = []) – The list of models to add. Each value in the list is a KModelDS and optional state data for the associated KModel.

• subtree_state_info (SubTreeStateDS | None = None) – State information for the SubTree.

• extra_info (SerializeAsAny[ExtraInfoType] | None = None) – Any extra information to store. This information is primarily used for validation of the SubTree and/or models. It is Python Generic, and can set by the user.

subtree: pydantic.SerializeAsAny[Karana.Dynamics.SOADyn_types.SubTreeDS[Karana.Dynamics.SOADyn_types.SubTreeDSType]]

models: list[tuple[pydantic.SerializeAsAny[Karana.Dynamics.SOADyn_types.KModelDS[Karana.Dynamics.SOADyn_types.BaseKModelType]], pydantic.SerializeAsAny[Karana.Dynamics.SOADyn_types.KModelStateDS[Karana.Dynamics.SOADyn_types.BaseKModelType]] | None]] = []

subtree_state_info: Karana.Dynamics.SOADyn_types.SubTreeStateDS | None = None

extra_info: pydantic.SerializeAsAny[ExtraInfoType] | None = None

class Karana.KUtils.BasicPrefab.BasicContext(/, **data: Any)

Bases: Karana.KUtils.Prefab.Context

Context for the BasicPrefab.

parent_body

The parent_body to attach bodies to from the subtree on params. If None, then a FrameContainer can be used if the subtree is a SubGraphDS. See frame_container above for details.

Type:

PhysicalBody | None = None

model_manager

The model_manager to register models with. If None and allow_create_model_manager is True in BasicConfig, then the BasicPrefab will attempt to create one.

Type:

ModelManager | None = None

frame_colliders

An optional list of FrameColliders. If provided, these will be used for any PenaltyContact models in-place of the FrameColliders that they have listed as part of their DataStruct.

Type:

list[FrameCollider] = []

parent_body_raw: Annotated[Karana.Dynamics.PhysicalBody | int | None, *SerializeAsId(allow_int=True, allow_None=True)] = None

model_manager_raw: Annotated[Karana.Dynamics.ModelManager | int | None, *SerializeAsId(allow_int=True, allow_None=True)] = None

frame_colliders_raw: list[Karana.Collision.FrameCollider | Karana.Collision.Collision_types.FrameColliderDS] = None

property frame_colliders: list[Karana.Collision.FrameCollider]

Get the FrameColliders for the associated PenaltyContact model.

Returns:

The FrameColliders for the associated PenaltyContact model.

Return type:

list[FrameCollider]

property model_manager: Karana.Dynamics.ModelManager | None

Return the ModelManager.

Returns:

The ModelManager if set. Otherwise, returns None.

Return type:

ModelManager | None

property parent_body: Karana.Dynamics.PhysicalBody | None

Get the parent_body.

Returns:

The parent_body if it is set. Otherwise, None is returned.

Return type:

PhysicalBody | None

class Karana.KUtils.BasicPrefab.BasicPrefab(name: str, config: ConfigType, context: ContextType, params: ParamsType, parent_prefab: Prefab[Any, Any, Any] | None = None)

Bases: Karana.KUtils.Prefab.Prefab[Karana.KUtils.Prefab.Config, BasicContext, BasicParams[ExtraInfoType]], Generic[ExtraInfoType]

BasicPrefab for holding multibody objects and KModels.

This BasicPrefab contains contains a SubTreeDS and a list of KModelDSs in its BasicParams. These are used to create multibody objects and KModels. See the associated BasicConfig, BasicContext, and BasicParams for how these can be used.

addMultibodyObjects()

Add multibody objects from params.

This adds the multibody objects stored in params.subtree.

If the context.parent_body is None, then no multibody objects will be added and a warning will be triggered.

addKModels()

Add KModels from params.

This method attempts to create KModels. To do so requires a ModelManager. This can be provided via context.model_manager.

If this value is None and there are models, a warning will be triggered.

toDS() → BasicPrefabDS[ExtraInfoType]

Create a BasicPrefabDS from this Prefab.

Returns:

The DataStruct that represents this Prefab.

Return type:

BasicPrefabDS[ExtraInfoType]

classmethod fromDS(data_struct: BasicPrefabDS[ExtraInfoType], parent_or_top: Prefab[Any, Any, Any] | None, *_, **kwargs) → Self

Convert the BasicPrefabDS to an instance of BasicPrefab.

This will also create instances of the associated children if applicable.

Parameters:

• data_struct (BasicPrefabDS[ExtraInfoType]) – The BasicPrefabDS[ExtraInfoType] to create an instance of this Prefab from.

• parent_or_top (Prefab[Any, Any, Any] | None) – The parent prefab or top_prefab. First, we will try to find the parent string from the PrefabDS on this value. If it exists, we will use that as the parent. Otherwise, we will use this as the parent directly. If None, then we will assume the Prefab being created is the top-level Prefab.

Returns:

An instance of this BasicPrefab.

Return type:

Self

classmethod createDS(name: str, config: Karana.KUtils.Prefab.Config, context: BasicContext, params: BasicParams[ExtraInfoType]) → BasicPrefabDS[ExtraInfoType]

Create a DataStruct representing a BasicPrefab.

This is a helper method to create the DataStruct version of Basic, without having to create an instance of Basic.

Parameters:

• name (str) – The name for the BasicPrefab.

• config (Config) – The Config for the BasicPrefab.

• context (BasicContext) – The BasicContext for the BasicPrefab.

• params (BasicParams[ExtraInfoType]) – The BasicParams for the BasicPrefab.

Returns:

The DataStruct representation of the BasicPrefab with the provided config, context, and params.

Return type:

PrefabDS[BasicConfig, BasicContext, BasicParams[ExtraInfoType]]

classmethod createStandalone(basic_prefab_ds: Karana.KUtils.Prefab.PrefabDS[Karana.KUtils.Prefab.Config, BasicContext, BasicParams[ExtraInfoType]], fc: Karana.Frame.FrameContainer) → tuple[Self, Karana.Dynamics.StatePropagator]

Create a simulation from a BasicPrefab DataStruct.

This creates an empty Multibody from the FrameContainer and an empty StatePropagator with the cvode integrator from the Multibody. Then, these are added to the BasicPrefab DataStruct’s context, and a BasicPrefab is created from it.

Parameters:

• basic_prefab_ds (PrefabDS[Config, BasicContext, BasicParams[ExtraInfoType]]) – The BasicPrefab DataStruct to use to construct the simulation.

• fc (FrameContainer) – The FrameContainer used to create the Multibody.

Returns:

An instance of the BasicPrefab and the StatePropagator created by this method.

Return type:

tuple[Self, StatePropagator]

class Karana.KUtils.BasicPrefab.BasicPrefabDS

Bases: Karana.KUtils.Prefab.PrefabDS[Karana.KUtils.Prefab.Config, BasicContext, BasicParams[ExtraInfoType]], Generic[ExtraInfoType]

A DataStruct representation of a BasicPrefab.

This is a thin wrapper around PrefabDS[Config, BasicContext, BasicParams[ExtraInfoType]] that provides a more ergonomic syntax and also allows overriding certain methods, e.g., to/fromFile.

classmethod fromPrefabDS(ds: Karana.KUtils.Prefab.PrefabDS[Karana.KUtils.Prefab.Config, BasicContext, BasicParams[ExtraInfoType]]) → Self

Convert a PrefabDS[Config, BasicContext, BasicParams[ExtraInfoType]] to a BasicPrefabDS.

Parameters:

ds (PrefabDS[Config, BasicContext, BasicParams[ExtraInfoType]]) – The PrefabDS[Config, BasicContext, BasicParams[ExtraInfoType]] to convert.

Returns:

The new instance of BasicPrefabDS created from the provided PrefabDS[Config, BasicContext, BasicParams[ExtraInfoType].

Return type:

Self

classmethod fromFile(file: pathlib.Path | str | IO[bytes], *, file_type: Literal['json', 'yaml', 'yml', 'h5', 'hdf5', 'pickle', 'pck', 'pcl'] | None = None, get_meta: Literal[False] = False) → Self

classmethod fromFile(file: pathlib.Path | str | IO[bytes], *, file_type: Literal['json', 'yaml', 'yml', 'h5', 'hdf5', 'pickle', 'pck', 'pcl'] | None = None, get_meta: Literal[True]) → tuple[Self, Karana.KUtils.DataStruct.Meta]

classmethod fromFile(file: pathlib.Path | str, *, file_type: Literal['urdf'] | None = None) → Self

classmethod fromFile(file: pathlib.Path | str, *, file_type: Literal['freecad'] | None = None) → Self

classmethod fromFile(g: h5py.Group, *, get_meta: Literal[False] = False) → Self

classmethod fromFile(g: h5py.Group, *, get_meta: Literal[True]) → tuple[Self, Karana.KUtils.DataStruct.Meta]

Create an instance of this DataStruct a file.

See overloads for details.

toFile(file: pathlib.Path | str | IO[bytes], file_type: Literal['json', 'yaml', 'yml', 'h5', 'hdf5', 'pickle', 'pck', 'pcl'] | None = None, meta: Karana.KUtils.DataStruct.Meta | None = None) → None

toFile(file: pathlib.Path | str, file_type: Literal['urdf'] | None = None) → None

toFile(g: h5py.Group, meta: Karana.KUtils.DataStruct.Meta | None = None) → None

Write the SubTreeDS to a file.

See overloads for details.