j2_cyclic_bounding_surface

J2 cyclic bounding surface plasticity for OpenSees nD elements.

Attributes

all `module-attribute`

__all__ = ['J2CyclicBoundingSurfaceMaterial']

Classes

Material

Material(material_type: str, material_name: str, user_name: str)

Bases: ABC

Abstract base class for manager-owned OpenSees material objects.

Material instances do not self-register and do not assign their own tags. A :class:~femora.core.material_manager.MaterialManager owns lifecycle operations, tag assignment, removal, and retagging for a local model context.

Parameters:

Name	Type	Description	Default
`material_type`	`str`	OpenSees material category (e.g. `'nDMaterial'`).	required
`material_name`	`str`	Concrete OpenSees material name (e.g. `'ElasticIsotropic'`).	required
`user_name`	`str`	User-specified label for this material instance.	required

Attributes:

Name	Type	Description
`tag`	`Optional[int]`	Manager-assigned OpenSees material tag. Remains `None` until this object is added to a :class:`~femora.core.material_manager.MaterialManager`.
`_owner`	`object \| None`	Reference to the owning manager, or `None` when unmanaged.

Methods:

to_tcl `abstractmethod`

to_tcl() -> str

Render the OpenSees material definition command as a Tcl string.

updateMaterialStage

updateMaterialStage(state: str) -> str

Return an updateMaterialStage Tcl command, or empty string.

set_parameter

set_parameter(parameter_name: str, new_value: Union[float, int, str, None] = None, element_tags: Optional[List[int]] = None) -> str

Return a setParameter Tcl command, or empty string.

get_param

get_param(key: str) -> Any

Return the value of a stored parameter by key.

J2CyclicBoundingSurfaceMaterial

J2CyclicBoundingSurfaceMaterial(user_name: str = 'Unnamed', *, G: float | None = None, K: float | None = None, Su: float | None = None, Den: float | None = None, h: float | None = None, m: float | None = None, h0: float | None = None, chi: float | None = None, beta: float = 0.5, **_: Any)

Bases: Material

Bounding-surface J2 plasticity for undrained cyclic loading.

Combines translational hardening on an inner yield surface with a bounding surface formulation suitable for cyclic clay-like behavior, with optional viscous damping term chi. Use this material when cyclic stiffness and strength degradation are needed but a full pressure-sensitive cap model is not required.

Tcl form

nDMaterial J2CyclicBoundingSurface <tag> G K Su Den h m h0 chi beta; #

Note

beta selects explicit (0), implicit (1), or midpoint (0.5) integration of the constitutive update.
Typical staged workflows use elastic and plastic states via updateMaterialStage.
Den may be zero for stiffness-only analyses.

Attributes:

Name	Type	Description
`params`		Validated stiffness, strength, density, hardening, damping, and integration parameters keyed for Tcl emission.

Example

from femora.core.model import Model

model = Model()
mat = model.material.nd.j2_cyclic_bounding_surface(
    user_name="clay_cyclic",
    G=12000.0,
    K=30000.0,
    Su=15.0,
    Den=1.82,
    h=20.0,
    m=0.2,
    h0=0.5,
    chi=0.02,
    beta=0.5,
)
print(mat.tag)

Create a J2 cyclic bounding surface material with validated parameters.

Parameters:

Name	Type	Description	Default
`user_name`	`str`	Instance label appended to Tcl and stored by the owning manager.	`'Unnamed'`
`G`	`float \| None`	Shear modulus, strictly positive.	`None`
`K`	`float \| None`	Bulk modulus, strictly positive.	`None`
`Su`	`float \| None`	Undrained shear strength, strictly positive.	`None`
`Den`	`float \| None`	Mass density for inertia or body-force coupling, `>= 0`.	`None`
`h`	`float \| None`	Hardening parameter controlling plastic modulus evolution.	`None`
`m`	`float \| None`	Hardening exponent shaping the nonlinear hardening curve.	`None`
`h0`	`float \| None`	Initial or reference hardening level.	`None`
`chi`	`float \| None`	Viscous damping coefficient used by the OpenSees model.	`None`
`beta`	`float`	Implicit-explicit blending weight on `[0, 1]`.	`0.5`
`**_`	`Any`	Ignored forward-compatibility keywords.	`{}`

Raises:

Type	Description
`ValueError`	If any mandatory parameter is missing.
`ValueError`	If a numeric parameter cannot be converted to `float`.
`ValueError`	If `G`, `K`, or `Su` is not positive, if `Den` is negative, or if `beta` falls outside `[0, 1]`.

Methods:

to_tcl

to_tcl() -> str

Render the defining Tcl command with parameters in fixed order.

Returns:

Name	Type	Description
`str`	`str`	Tcl line `nDMaterial J2CyclicBoundingSurface` followed by the
	`str`	tag and `G K Su Den h m h0 chi beta` values.

Raises:

Type	Description
`ValueError`	If the material is unmanaged.

updateMaterialStage

updateMaterialStage(state: str) -> str

Emit Tcl to switch elastic versus plastic modulus stages.

Parameters:

Name	Type	Description	Default
`state`	`str`	Case-insensitive stage name. `"elastic"` selects stage `0` and `"plastic"` selects stage `1`.	required

Returns:

Name	Type	Description
`str`	`str`	The `updateMaterialStage` Tcl snippet for the matched state,
	`str`	or an empty string when `state` is unrecognized.

Raises:

Type	Description
`ValueError`	If the material is unmanaged when a supported state is requested.

j2_cyclic_bounding_surface