sp_load

sp_load

Attributes

__all__ module-attribute

__all__ = ['SpLoad']

Classes

Load

Load()

Bases: ABC

Base class for OpenSees load commands emitted inside a pattern Plain block.

Load instances do not self-register. A :class:LoadManager owns tag assignment and lifecycle for a single model context.

SpLoad

SpLoad(*, dof: int, value: float, node_tag: Optional[int] = None, node_mask: Optional[object] = None, pids: Optional[List[int]] = None)

Bases: Load

Single-point load component for applying values to a specific degree of freedom.

SpLoad represents a single-point boundary value applied to a specific DOF at a node. It is typically registered under a Plain pattern to prescribe displacements or boundary loads.

Tcl form

sp <nodeTag> <dof> <value>

Note

• The degree of freedom (dof) is 1-indexed (e.g., 1 for X, 2 for Y).
• If a node_mask is provided, the single-point load is applied to all selected nodes.
• In parallel computing contexts, partition IDs (pids) specify which processor core(s) should execute the command.

Example

from femora.core.model import Model

model = Model()
ts = model.time_series.constant(factor=1.0)
pattern = model.pattern.plain(time_series=ts)

# Apply a prescribed value of -5.0 to DOF 2 of node 3
load = pattern.add_load.sp(
    node_tag=3,
    dof=2,
    value=-5.0,
)

Create a single-point load component.

Parameters:

Name	Type	Description	Default
dof	int	1-indexed degree of freedom (DOF) to apply the value to.	required
value	float	Numerical value of the applied single-point excitation.	required
node_tag	Optional[int]	Optional explicit tag of the target node.	None
node_mask	Optional[object]	Optional NodeMask object to apply this load to multiple nodes.	None
pids	Optional[List[int]]	Optional processor partition IDs for parallel execution.	None

Raises:

Type	Description
ValueError	If neither node_tag nor node_mask is specified, if node_mask is not a NodeMask, or if input validation fails.

Methods:

to_tcl

to_tcl() -> str

Render this single-point load as OpenSees Tcl commands.

Returns:

Type	Description
str	The OpenSees sp command string(s) for the node(s).

Functions:

_coerce_positive_int

_coerce_positive_int(value: Any, field: str) -> int

Coerce a value to a positive integer.

Parameters:

Name	Type	Description	Default
value	Any	The value to be converted.	required
field	str	The name of the field being validated (for error messages).	required

Returns:

Type	Description
int	The validated positive integer.

Raises:

Type	Description
ValueError	If the value cannot be converted to a positive integer or is less than 1.

_coerce_float

_coerce_float(value: Any, field: str) -> float

Coerce a value to a float.

Parameters:

Name	Type	Description	Default
value	Any	The value to be converted.	required
field	str	The name of the field being validated.	required

Returns:

Type	Description
float	The validated float value.

Raises:

Type	Description
ValueError	If the value cannot be converted to a float.

_coerce_pids

_coerce_pids(pids: Any) -> List[int]

Coerce partition IDs to a sorted list of unique integers.

Parameters:

Name	Type	Description	Default
pids	Any	The partition IDs (list or tuple) to be validated.	required

Returns:

Type	Description
List[int]	A sorted list of unique validated integers.

Raises:

Type	Description
ValueError	If the input is not a list or tuple of integer values.