Clump

class itasca.clump.Clump

Objects of this type should not be created (instantiated) directly in Python. Use the module functions that return instances of this type.

add_pebble(pebble_radius: float, pebble_centroid: vec[, id: int]) → Pebble object.

Add a pebble to a clump. This operation has no impact on the clump inertial attributes. The clump no longer refers to a clump template. The pebble must fall within the model domain.

calculate(error_percentage=0.01) → None.

Calculate the clump interial properties. The optional error_percentage argument should be in the range 0.0005 < x < 1. The current pebble distribution is used with a voxelation approach to calculate the interial properties within a specified error. See the clump template command for further details. The pebbles are not translated but the clump centroid location may be modified. The moment of inertia will be modified by changes in volume or density after this operation.

contact_count(all=False, type=None) → int.

Get the number of contacts associated with this clump. If the optional keyword argument type is given, the count is limited to the contact types specified. The type keyword argument should be a Python type object (one of: itasca.BallBallContact, itasca.BallPebbleContact, itasca.PebblePebbleContact, itasca.BallFacetContact or itasca.PebbleFacetContact). If the (optional) keyword argument all is True the count includes virtual contacts.

contacts([piece: object, ]all=False, type=None) → Tuple of Contact objects.

Get a tuple of contacts associated with this clump. An optional argument can be included which is a piece object (a Ball, a Pebble or a Facet). If the optional keyword argument type is given, the returned list is limited to the contact types specified. The type keyword argument should be a Python type object (one of: itasca.BallBallContact, itasca.BallPebbleContact, itasca.PebblePebbleContact, itasca.BallFacetContact or itasca.PebbleFacetContact). If the (optional) keyword argument all is True the returned list includes virtual contacts.

damp() → float.

Get the clump local damping.

delete() → None.

Delete this clump.

delete_pebble(pebble: Pebble object) → None.

Delete a pebble from this clump. This operation has no impact on the clump inertial attributes. The clump no longer refers to a clump template.

density() → float.

Get the clump density.

disp() → vec.

Get the clump displacement (vector).

disp_x() → float.

Get the x-component of the clump displacement.

disp_y() → float.

Get the y-component of the clump displacement.

disp_z() → float.

Get the z-component of the clump displacement.

euler() → vec.

Get the clump orientation (vector).

euler_x() → float.

Get the x-component of the clump orientation.

euler_y() → float.

Get the y-component of the clump orientation.

euler_z() → float.

Get the z-component of the clump orientation.

extra(slot: int) → any.

Get the clump extra data in the given slot.

fix(component: int) → bool.

Get the clump fixity condition. The integer degree-of-freedom cooresponds to the following order: in 3D: 0) x-velocity, 1) y-velocity, 2) z-velocity, 3) x-angular velocity, 4) y-angular velocity, 5) z-angular velocity. in 2D: 0) x-velocity, 1) y-velocity, 2) angular velocity. The return value is false for free and true for fixed conditions.

force_app() → vec.

Get the clump applied force (vector).

force_app_x() → float.

Get the x-component of the clump applied force.

force_app_y() → float.

Get the y-component of the clump applied force.

force_app_z() → float.

Get the z-component of the clump applied force.

force_contact() → vec.

Get the clump contact force (vector).

force_contact_x() → float.

Get the x-component of the clump contact force.

force_contact_y() → float.

Get the y-component of the clump contact force.

force_contact_z() → float.

Get the z-component of the clump contact force.

force_unbal() → vec.

Get the clump unbalanced force (vector).

force_unbal_x() → float.

Get the x-component of the clump unbalanced force.

force_unbal_y() → float.

Get the y-component of the clump unbalanced force.

force_unbal_z() → float.

Get the z-component of the clump unbalanced force.

fragment() → int.

Get the clump fragment ID.

group([slot: str or int]) → str.

Get the clump group name in a given slot.

group_remove(group_name: str or int[, slot: str or int]) → bool.

Remove from the given group from all group slots of the clump. One argument of type string, giving the group name, is required. The return value is a bool which is True if the group was removed from any slot, otherwise False.

groups() → {slot: group_name}.

Get a dictionary describing which groups this clump is part of. The keys of the dictionary are the slot names and the values are the group names.

id() → int.

Get the clump id.

in_group(group_name: str or int[, slot: str or int]) → bool.

Test if the clump is part of a given group. If the optional argument slot is given, only that slot is searched. Otherwise, all group slots are searched.

inside(point: vec) → bool.

Test whether a point is inside a clump.

mass() → float.

Get the clump inertial mass.

mass_real() → float.

Get the clump real (gravitational) mass.

moi() → tensor.

Get the clump moment of intertia. In 2D the polar moment of intertial is used so the return value is a float.

moi_fix() → bool.

Get the moment of intertia fixity state. When activated, the clump moment of inertia will not be automatically updated when a clump is scaled, the volume is changed, or when the density is changed. This is activated automatically when either the volume or moment of inertia is set manually via the clump attribute command or via the Clump object methods vol(), moi_real() or moi_prinreal().

moi_prin() → vec.

Get the clump principal moment of inertia (vector).

moi_prin_real() → vec.

Get the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method) (vector).

moi_prin_real_x() → float.

Get the x-component of the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method).

moi_prin_real_y() → float.

Get the y-component of the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method).

moi_prin_real_z() → float.

Get the z-component of the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method).

moi_prin_x() → float.

Get the x-component of the clump principal moment of inertia.

moi_prin_y() → float.

Get the y-component of the clump principal moment of inertia.

moi_prin_z() → float.

Get the z-component of the clump principal moment of inertia.

moi_real() → tensor.

Get the clump real moment of intertia. In 2D the polar moment of intertial is used so the return value is a float.

moment_app() → vec.

Get the clump applied moment (vector).

moment_app_x() → float.

Get the x-component of the clump applied moment.

moment_app_y() → float.

Get the y-component of the clump applied moment.

moment_app_z() → float.

Get the z-component of the clump applied moment.

moment_contact() → vec.

Get the clump contact moment (vector).

moment_contact_x() → float.

Get the x-component of the clump contact moment.

moment_contact_y() → float.

Get the y-component of the clump contact moment.

moment_contact_z() → float.

Get the z-component of the clump contact moment.

moment_unbal() → vec.

Get the clump unbalanced moment (vector).

moment_unbal_x() → float.

Get the x-component of the clump unbalanced moment.

moment_unbal_y() → float.

Get the y-component of the clump unbalanced moment.

moment_unbal_z() → float.

Get the z-component of the clump unbalanced moment.

pebbles() → Pebble iterator object.

Get the pebbles of this clump.

pos() → vec.

Get the clump centroid location (vector).

pos_x() → float.

Get the x-component of the clump centroid location.

pos_y() → float.

Get the y-component of the clump centroid location.

pos_z() → float.

Get the z-component of the clump centroid location.

rotate(axis: vec, rotation_angle: float) → None.

Rotate a clump. The rotation point is the clump position and it is rotated in a right handed sense about the given axis by rotation_angle degrees.

scale_sphere(diameter: float) → None.

Scale the clump to an equivalent sphere. The clump is scaled so that its {area in 2D; volume in 3D} is the same as a {circle in 2D; sphere in 3D} of the given diameter. The pebbles are scaled, their positions are modified and the volume is updated. All pebbles of the scaled clump must fall within the model domain for the operation to succeed. If the volume or moment of inertia has been previously specified by the user either via clump attribute or via the Clump object methods (vol(), moi_prin_real() or moi_real()), the principal moment of inertial is in a fixed state and will not be scaled. See the Cump object moi_fix() method for further details.

scale_vol(volume: float) → None.

Scale the clump. The clump is scaled so that its {volume per unit thickness in 2D; volume in 3D} is as specified. The pebbles are scaled, their positions are modified and the volume is updated. All pebbles of the scaled clump must fall within the model domain for the operation to succeed. If the volume or moment of inertia has been previously specified by the user either via clump attribute or via the Clump object methods (vol(), moi_prin_real() or moi_real()), the principal moment of inertial is in a fixed state and will not be scaled. See the Cump object moi_fix() method for further details.

set_damp(value: float) → None.

Set the clump local damping.

set_density(value: float) → None.

Set the clump density.

set_disp(value: vec) → None.

Set the clump displacement (vector).

set_disp_x(value: float) → None.

Set the x-component of the clump displacement.

set_disp_y(value: float) → None.

Set the y-component of the clump displacement.

set_disp_z(value: float) → None.

Set the z-component of the clump displacement.

set_euler(value: vec) → None.

Set the clump orientation (vector).

set_euler_x(value: float) → None.

Set the x-component of the clump orientation.

set_euler_y(value: float) → None.

Set the y-component of the clump orientation.

set_euler_z(value: float) → None.

Set the z-component of the clump orientation.

set_extra(slot: int, value: any) → None.

Set the clump extra data in the given slot.

set_fix(component: int, fixity: bool) → None.

Get the clump fixity condition. The integer degree-of-freedom cooresponds to the following order: in 3D: 1) x-velocity, 2) y-velocity, 3) z-velocity, 4) x-angular velocity, 5) y-angular velocity, 6) z-angular velocity. in 2D: 1) x-velocity, 2) y-velocity, 3) angular velocity. The fixity value is false for free and true for fixed conditions.

set_force_app(value: vec) → None.

Set the clump applied force (vector).

set_force_app_x(value: float) → None.

Set the x-component of the clump applied force.

set_force_app_y(value: float) → None.

Set the y-component of the clump applied force.

set_force_app_z(value: float) → None.

Set the z-component of the clump applied force.

set_force_contact(value: vec) → None.

Set the clump contact force (vector).

set_force_contact_x(value: float) → None.

Set the x-component of the clump contact force.

set_force_contact_y(value: float) → None.

Set the y-component of the clump contact force.

set_force_contact_z(value: float) → None.

Set the z-component of the clump contact force.

set_fragment(id: int) → None.

Set clump fragment ID.

set_group(group_name: str or int[, slot: str or int]) → None.

Set the clump group name in a given slot.

set_moi_fix(fixity: bool) → None.

Set the moment of intertia fixity state. When activated, the clump moment of inertia will not be automatically updated when a clump is scaled, the volume is changed, or when the density is changed. This is activated automatically when either the volume or moment of inertia is set manually via the clump attribute command or via the Clump object methods vol(), moi_real() or moi_prinreal().

set_moi_prin_real(value: vec) → None.

Set the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method) (vector).

set_moi_prin_real_x(value: float) → None.

Set the x-component of the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method).

set_moi_prin_real_y(value: float) → None.

Set the y-component of the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method).

set_moi_prin_real_z(value: float) → None.

Set the z-component of the clump real principal moment of inertia. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method).

set_moi_real() → tensor.

Get the clump real moment of intertia. In 2D the polar moment of intertial is used so the return value is a float. When modified no other clump attributes are changed (e.g., pebble sizes, clump volume, etc.). The specification of the moment of inertia in this way results in the principal moments of inertia being in a fixed state so that they will not be automatically updated when scaling a clump unless the user changes the fix state (see the Clump moi_fix() method).

set_moment_app(value: vec) → None.

Set the clump applied moment (vector).

set_moment_app_x(value: float) → None.

Set the x-component of the clump applied moment.

set_moment_app_y(value: float) → None.

Set the y-component of the clump applied moment.

set_moment_app_z(value: float) → None.

Set the z-component of the clump applied moment.

set_moment_contact(value: vec) → None.

Set the clump contact moment (vector).

set_moment_contact_x(value: float) → None.

Set the x-component of the clump contact moment.

set_moment_contact_y(value: float) → None.

Set the y-component of the clump contact moment.

set_moment_contact_z(value: float) → None.

Set the z-component of the clump contact moment.

set_pos(value: vec) → None.

Set the clump centroid location (vector).

set_pos_x(value: float) → None.

Set the x-component of the clump centroid location.

set_pos_y(value: float) → None.

Set the y-component of the clump centroid location.

set_pos_z(value: float) → None.

Set the z-component of the clump centroid location.

set_spin(value: vec) → None.

Set the clump angular velocity (vector).

set_spin_x(value: float) → None.

Set the x-component of the clump angular velocity.

set_spin_y(value: float) → None.

Set the y-component of the clump angular velocity.

set_spin_z(value: float) → None.

Set the z-component of the clump angular velocity.

set_vel(value: vec) → None.

Set the clump velocity (vector).

set_vel_x(value: float) → None.

Set the x-component of the clump velocity.

set_vel_y(value: float) → None.

Set the y-component of the clump velocity.

set_vel_z(value: float) → None.

Set the z-component of the clump velocity.

set_vol(value: float) → None.

Set the clump volume. In 2D this is the volume per unit thickness.

spin() → vec.

Get the clump angular velocity (vector).

spin_x() → float.

Get the x-component of the clump angular velocity.

spin_y() → float.

Get the y-component of the clump angular velocity.

spin_z() → float.

Get the z-component of the clump angular velocity.

template() → Template object or None.

Get the template associated with this clump. The result will be None if no Template is associated with this clump.

template_euler() → vec.

Get the clump template relative orientation (vector).

template_euler_x() → float.

Get the x-component of the clump template relative orientation.

template_euler_y() → float.

Get the y-component of the clump template relative orientation.

template_euler_z() → float.

Get the z-component of the clump template relative orientation.

template_scale() → float.

Get the clump template relative scaling factor.

to_global(value: vec) → vec.

Rotate a vector from principal system. The returned vector is in the global axis system.

to_prin(value: vec) → vec.

Rotate a vector to principal system.

valid() → bool.

Returns True if this clump is live.

vel() → vec.

Get the clump velocity (vector).

vel_x() → float.

Get the x-component of the clump velocity.

vel_y() → float.

Get the y-component of the clump velocity.

vel_z() → float.

Get the z-component of the clump velocity.

vol() → float.

Get the clump volume. In 2D this is the volume per unit thickness.