Index

Micromechanical modeling of granular materials.

__all__ module-attribute

__all__ = [
    "backends",
    "config",
    "Experiment",
    "get_include",
    "Line",
    "Model",
    "register_model",
    "SVExporter",
    "tr",
    "trs",
    "visualize_calibration",
    "__version__",
    "__semver__",
]

__semver__ module-attribute

__semver__: str = __version__.split('+')[0]

__version__ module-attribute

__version__: str = _get_version()

tr module-attribute

tr = translate

trs module-attribute

trs = translate_string

Experiment

Bases: HashableBaseModelIO

An experiment.

caches class-attribute

caches: Dict[str, LRUCache] = {
    "getitem": cachetools.LRUCache(maxsize=128),
    "__getitem__": cachetools.LRUCache(maxsize=128),
}

caches for the getitem and getitem methods

lines class-attribute instance-attribute

lines: Dict[str, Line] = {}

list of lines in the experiment

name instance-attribute

name: str

name of the experiment

notes class-attribute instance-attribute

notes: Dict[str, Any] = {}

custom notes for the experiment, only for labelling purposes and not used in the calculation

options class-attribute instance-attribute

options: Dict[str, Any] = {}

options for the micromechanical-specific model, used in :meth:micromechanical.Model.setCalculationOptions to set the calculation options for the model

phases class-attribute instance-attribute

phases: Dict[str, LoadPhaseIO] = {}

load phases of the experiment

__contains__

__contains__(item: Tuple[str, str]) -> bool

Return whether a line exists.

PARAMETER	DESCRIPTION
item	Names of the x-axis and y-axis of the line. TYPE: Tuple[str, str]

RETURNS	DESCRIPTION
bool	True if the line exists, False otherwise.

__getitem__

__getitem__(item: Tuple[str, str]) -> Tuple[ndarray, ndarray]

Return the x-axis and y-axis data of a line.

PARAMETER	DESCRIPTION
item	Names of the x-axis and y-axis of the line. TYPE: Tuple[str, str]

RETURNS	DESCRIPTION
Tuple[ndarray, ndarray]	The x-axis and y-axis data of the line.

addConfinementPhase

addConfinementPhase(eps1: float, steps: int) -> LoadPhaseIO

Add a confinement load phase.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
eps1	Maximum strain. TYPE: float

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

addConstantStressRatioPhase

addConstantStressRatioPhase(
    sig3_min: float, sig3_max: float, eta: float, steps: int, axis: int = 1
) -> LoadPhaseIO

Add a constant stress ratio load phase.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
sig3_min	Minimum value of minimum principal stress. TYPE: float
sig3_max	Maximum value of minimum principal stress. TYPE: float
eta	Constant stress ratio. TYPE: float
axis	Loading axis, by default 1 TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
LoadPhase	The load phase.

addDrainedTriaxialPhase

addDrainedTriaxialPhase(
    sigc: float, eps1: float, steps: int, axis: int = 1
) -> LoadPhaseIO

Add a drained triaxial load phase.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
sigc	Confined stress. TYPE: float
eps1	Maximum strain. TYPE: float
axis	Loading axis, by default 1 TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

addIsotropicPhase

addIsotropicPhase(sigc: float, steps: int) -> LoadPhaseIO

Add an isotropic load phase.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
sigc	Confined stress. TYPE: float

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

addLoadPhase

addLoadPhase(name: str, phase: LoadPhaseIO | LoadPhase) -> LoadPhaseIO

Add a load phase.

PARAMETER	DESCRIPTION
name	Name of the load phase. TYPE: str
phase	The load phase, if not an instance of LoadPhaseIO, it will be converted to one. TYPE: LoadPhaseIO | LoadPhase

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

addTrueTriaxialPhase

addTrueTriaxialPhase(
    sig3: float,
    b: float,
    eps1: float,
    steps: int,
    axis1: int = 1,
    axis2: int = 2,
) -> LoadPhaseIO

Add a true triaxial load phase.

PARAMETER	DESCRIPTION
sig3	Minimum principal stress. TYPE: float
b	Intermediate stress ratio. TYPE: float
eps1	Maximum strain. TYPE: float
steps	Number of steps. TYPE: int
axis1	Major axis, by default 1 TYPE: int DEFAULT: 1
axis2	Intermediate axis, by default 2 TYPE: int DEFAULT: 2

RETURNS	DESCRIPTION
LoadPhase	The load phase.

addTrueTriaxialWithConstantShearPhase

addTrueTriaxialWithConstantShearPhase(
    p: float, b: float, steps: int, axis1: int = 1, axis2: int = 2
) -> LoadPhaseIO

Add a true triaxial load phase.

PARAMETER	DESCRIPTION
p	Mean stress. TYPE: float
b	Lode parameter. TYPE: float
steps	Number of steps. TYPE: int
axis1	Major axis, by default 1 TYPE: int DEFAULT: 1
axis2	Intermediate axis, by default 2 TYPE: int DEFAULT: 2

RETURNS	DESCRIPTION
LoadPhase	The load phase.

addUndrainedTriaxialPhase

addUndrainedTriaxialPhase(
    eps1: float, steps: int, axis: int = 1, no_epsv: bool = False
) -> LoadPhaseIO

Add an undrained triaxial load phase.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
eps1	Maximum strain. TYPE: float
axis	Loading axis, by default 1 TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

addUndrainedTriaxialWithoutShearPhase

addUndrainedTriaxialWithoutShearPhase(
    eps1: float, steps: int, axis: int = 1, no_epsv: bool = False
) -> LoadPhaseIO

Add an undrained triaxial load phase without controlling the shear strain.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
eps1	Maximum strain. TYPE: float
axis	Loading axis, by default 1 TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

addUndrainedTrueTriaxialPhase

addUndrainedTrueTriaxialPhase(
    eps1: float,
    b: float,
    steps: int,
    axis1: int = 1,
    axis2: int = 2,
    no_epsv: bool = True,
) -> LoadPhaseIO

Add an undrained true triaxial load phase.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
eps1	Maximum strain. TYPE: float
b	Intermediate stress ratio. TYPE: float
axis1	Major axis, by default 1 TYPE: int DEFAULT: 1
axis2	Intermediate axis, by default 2 TYPE: int DEFAULT: 2
no_epsv	Whether to control the intermediate principal stress without generating volumetric strain, this is useful when the material fabric is non-coaxial with the principal stress, by default True TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

addUndrainedTrueTriaxialWithAxialStrainPhase

addUndrainedTrueTriaxialWithAxialStrainPhase(
    epsa: float,
    b: float,
    steps: int,
    axis1: int = 1,
    axis2: int = 2,
    no_epsv: bool = True,
) -> LoadPhaseIO

Add an undrained true triaxial load phase with axial strain control.

PARAMETER	DESCRIPTION
steps	Number of steps. TYPE: int
epsa	Axial strain. TYPE: float
b	Intermediate stress ratio. TYPE: float
axis1	Major axis, by default 1 TYPE: int DEFAULT: 1
axis2	Intermediate axis, by default 2 TYPE: int DEFAULT: 2
no_epsv	Whether to control the intermediate principal stress without generating volumetric strain, this is useful when the material fabric is non-coaxial with the principal stress, by default True TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
LoadPhaseIO	The load phase.

check

check(raise_: bool = True) -> bool | None

Check whether the experiment is valid.

PARAMETER	DESCRIPTION
raise_	Whether to raise an error if the experiment is invalid, by default True TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
bool | None	True if the experiment is valid, False if the experiment is invalid, None if the experiment is not checked.

get

get(
    x: str,
    y: str | None = None,
    *,
    deep: bool = False,
    idx: int | Iterable[int] | slice = None
) -> Tuple[ndarray, ndarray] | ndarray

Return the x-axis and y-axis data of a line.

PARAMETER	DESCRIPTION
x	Name of the x-axis of the line. TYPE: str
y	Name of the y-axis of the line. If None, only the x-axis data will be returned. TYPE: str DEFAULT: None
deep	Search for the line deeply in the experiment, by default False to avoid RecursionError. TYPE: bool DEFAULT: False
idx	Index of the data to be returned, by default None to return all data. TYPE: int | Iterable[int] | slice DEFAULT: None

RETURNS	DESCRIPTION
Tuple[ndarray, ndarray] | ndarray	The x-axis and y-axis data of the line, or only the x-axis data if y is None.

getitem

getitem(item: Tuple[str, str]) -> Tuple[ndarray, ndarray]

Return the x-axis and y-axis data of a line, only for exactly matching lines or expressions that can be evaluated to the x-axis and y-axis names.

PARAMETER	DESCRIPTION
item	Names of the x-axis and y-axis of the line. TYPE: Tuple[str, str]

RETURNS	DESCRIPTION
Tuple[ndarray, ndarray]	The x-axis and y-axis data of the line.

Line

Bases: HashableBaseModelIO

A line for an experiment.

max property

max: float

Return the maximum value of the line.

min property

min: float

Return the minimum value of the line.

ptp property

ptp: float

Return the peak-to-peak value of the line.

x instance-attribute

x: str

x-axis name of the line, used in :meth:micromechanical.python.micromechanical.core.StateVariables.get to get the x-axis data

xdata instance-attribute

xdata: List[float]

x-axis experimental data

y instance-attribute

y: str

y-axis name of the line, used in :meth:micromechanical.python.micromechanical.core.StateVariables.get to get the y-axis data

ydata instance-attribute

ydata: List[float]

y-axis experimental data

Model

Bases: VisualizationModel

A micromechanical model manager.

Notes

The main calculation of the micromechanical model is done in the model attribute, which is an instance of the pure Python/numba/C++ micromechanical model, depending on the backend. Setting the following environment variables to change the backend:

• MICROMECHANICAL_BACKEND=cpp: use the C++ backend
• MICROMECHANICAL_BACKEND=python;NUMBA_DISABLE_JIT=1: use the pure Python backend
• MICROMECHANICAL_BACKEND=python;NUMBA_DISABLE_JIT=0: use the numba backend

For the cpp and numba backends, the environment variable MICROMECHANICAL_PRECISION can be set to single or double to change the precision, the default is double

Examples:

Create the micromechanical model object:

>>> from micromechanical import Model
>>> model = Model("CH-OSIMSAND")

Set up the loading phases:

>>> model.addIsotropicPhase(sigc=-100, steps=100)
>>> model.addDrainedTriaxialPhase(sigc=-100, eps1=-0.3, steps=100)

Set up the plastic method for the local contact law:

>>> model.setPlasticMethod("CPA")  # default is "CPA"

Set up integration points:

>>> model.setIntegrationParameters(npv=1e9, radius=0.65e-3)
>>> model.setAnisotropicParameters(type="chang1990-ext", evolution="wan2004", chi=0)

Set up material parameters:

>>> model.setParameters(phi=30)

Evaluate the model:

>>> sv = model.run()
Running CH-OSIMSAND model ...
Finished in ... seconds.

sv is a micromechanical.SVExporter object, which can be used to get the state variables, plot the results, and export the results to a file.

>>> sv.to_csv("data.csv")
Saving state variables to DataFrame
>>> p, q, epsa, epsv = sv.get("-p"), sv.q, 100 * sv["epsa"], sv["100 * epsv"]  # the tensile stress is positive
>>> model.plot("-p", "q", data=sv)  # if data is omitted, model.run() will be called
<Figure size ... with 1 Axes>

__init__

__init__(
    *model_types: Union[
        MicromechanicalBase,
        type,
        str | PathLike,
        AvailableModels,
        AvailableMicromechanicalModels,
        AvailableContactModels,
    ],
    args: tuple = (),
    kwargs: dict = None,
    no_stop: bool = False,
    backend: Literal["python", "cpp"] = backend,
    **options
)

Constructor for the micromechanical model manager base class.

PARAMETER	DESCRIPTION
model_types	The micromechanical model to use. If no positional arguments are provided, the model will not be initialized. If one positional argument is provided, it should be: a micromechanical model object a micromechanical model class a string of the form model_type-contact_type If two positional arguments are provided, they should be: (model_type | model_plugin_path, contact_type | contact_plugin_path) In C++ backend, the micromechanical model type and contact law type can be a string of the file path to the compiled shared library. For example, the following usages are valid: model = Model(ChangHicherElasticModel): use the ChangHicherElasticModel class (Python) model = Model(ChangHicherElasticModel()): use the ChangHicherElasticModel object (Python) model = Model("CH-Elastic"): use the CH model with the Elastic contact law model = Model("CH", "Elastic"): use the CH model with the Elastic contact law model = Model("CH", "elastic.dll"): use the CH model with the elastic.dll shared library (C++) model = Model("changhicher.dll", "Elastic"): use the changhicher.dll shared library with the Elastic contact law (C++) model = Model("changhicher.dll", "elastic.dll"): use the changhicher.dll shared library with the elastic.dll shared library (C++) TYPE: Union[MicromechanicalBase, type, str | PathLike, AvailableModels, AvailableMicromechanicalModels, AvailableContactModels] DEFAULT: ()
args	The positional arguments for the micromechanical model if the supplied model is a class. TYPE: tuple DEFAULT: ()
kwargs	The keyword arguments for the micromechanical model if the supplied model is a class. TYPE: dict DEFAULT: None
no_stop	Whether to stop the calculation when an error occurs. TYPE: bool DEFAULT: False
backend	The backend to use, default is the configured backend. TYPE: ('python', 'cpp') DEFAULT: "python"
options	The calculation options for the micromechanical model, the contact law, or the material. DEFAULT: {}

SVExporter

Bases: UserList

State variables exporter to handle a list of state variables. The constructor of the SVExporter class accepts a list of StateVariable objects:

>>> from micromechanical.python.constitutive.statevariable import StateVariable
>>> sv0, sv1 = StateVariable(37), StateVariable(37)
>>> sv0.phase, sv1.phase = 0, 1
>>> exporter = SVExporter([sv0] * 60 + [sv1] * 40)

There are three ways to get state variables:

1. Get the state variables by name, e.g. exporter.sig implemented by SVExporter.__getattr__ method. the state variables will be cached. This method will collect a specific state variable from all the state variables in the list, and return a numpy array with the first dimension being the step index. The returned array can be a 1D array, a 2D array or a 3D array, depending on the shape of the state variable.

   >>> exporter.epsa.shape
   (100,)
   >>> exporter.sig.shape
   (100, 6)
   >>> exporter.disp.shape
   (100, 37, 3)
   

2. Get the state variables by name or expression of the name or name with column index, e.g., exporter["sig"], implemented by SVExporter.__getitem__.

   >>> exporter["sig1"].shape
   (100,)
   >>> exporter["epsa * 100"].shape
   (100,)
   

3. Get the state variables by the above name with filters, implemented by the SVExporter.get method. This method is used to determine the state variables to get in visualization methods such as VisualizationModel.plot and x/y axis of the experiment Line.

   The following filters are supported:

   • phase: load phase index
   • step: step index
   • idx: integration point index, only valid for contact state variables
   • col: column index, only valid for vector state variables

   You can use the filters by the keyword arguments.

   >>> exporter.get("disp", phase=0).shape
   (60, 37, 3)
   >>> exporter.get("disp", step=slice(80)).shape
   (80, 37, 3)
   >>> exporter.get("disp", step=slice(80, None)).shape
   (20, 37, 3)
   >>> exporter.get("disp", idx=slice(20)).shape
   (100, 20, 3)
   >>> exporter.get("disp", col=0).shape
   (100, 37)
   

Note

The above filters are applied with the following steps:

• If phase is specified, the state variables will be filtered by the phase index first.
• An array of the indices of the steps corresponding to the phase will be generated by the SVExporter.indexOf method.
• An array of the state variable will be generated by the SVExporter.__getitem__ method, and then filtered by the indices of the steps.
• If the array is a 3D array, it will be filtered by the step index, integration point index and column index in each dimension, i.e., array[step, idx, col].
• If the array is a 2D array, depending on the name of the state variable, it will be filtered by the step index and integration point index if the state variable is a contact state variable (i.e., array[step, idx]), or filtered by the step index and column index otherwise (i.e., array[step, col]) .
• If the array is a 1D array, it will be filtered by the step index, i.e., array[step].

Note

Property fabric tensors can be obtained by the name F_{prop} where {prop} is the property name.

You can also export the state variables to a pandas DataFrame by the SVExporter.toDataFrame method.

>>> df = exporter.toDataFrame(includes=["sig", "eps"])
Saving state variables to DataFrame
>>> df.head()
   eps1  eps2  eps3  eps4  eps5  eps6  sig1  sig2  sig3  sig4  sig5  sig6
...

Then it is possible to export the DataFrame to any file format supported by pandas, e.g., csv, excel, etc.

A instance-attribute

A: ndarray

Fabric tensor, shape (steps, 6)

A11 instance-attribute

A11: ndarray

Fabric tensor component A11, shape (steps,)

A12 instance-attribute

A12: ndarray

Fabric tensor component A12, shape (steps,)

A13 instance-attribute

A13: ndarray

Fabric tensor component A13, shape (steps,)

A22 instance-attribute

A22: ndarray

Fabric tensor component A22, shape (steps,)

A23 instance-attribute

A23: ndarray

Fabric tensor component A23, shape (steps,)

A33 instance-attribute

A33: ndarray

Fabric tensor component A33, shape (steps,)

F instance-attribute

F: ndarray

Fabric tensor, shape (steps, 6)

F11 instance-attribute

F11: ndarray

Fabric tensor component F11, shape (steps,)

F12 instance-attribute

F12: ndarray

Fabric tensor component F12, shape (steps,)

F13 instance-attribute

F13: ndarray

Fabric tensor component F13, shape (steps,)

F22 instance-attribute

F22: ndarray

Fabric tensor component F22, shape (steps,)

F23 instance-attribute

F23: ndarray

Fabric tensor component F23, shape (steps,)

F33 instance-attribute

F33: ndarray

Fabric tensor component F33, shape (steps,)

FN11 instance-attribute

FN11: ndarray

Fabric tensor of contact normal force component FN11, shape (steps,)

FN12 instance-attribute

FN12: ndarray

Fabric tensor of contact normal force component FN12, shape (steps,)

FN13 instance-attribute

FN13: ndarray

Fabric tensor of contact normal force component FN13, shape (steps,)

FN22 instance-attribute

FN22: ndarray

Fabric tensor of contact normal force component FN22, shape (steps,)

FN23 instance-attribute

FN23: ndarray

Fabric tensor of contact normal force component FN23, shape (steps,)

FN33 instance-attribute

FN33: ndarray

Fabric tensor of contact normal force component FN33, shape (steps,)

FT11 instance-attribute

FT11: ndarray

Fabric tensor of contact shear force component FT11, shape (steps,)

FT12 instance-attribute

FT12: ndarray

Fabric tensor of contact shear force component FT12, shape (steps,)

FT13 instance-attribute

FT13: ndarray

Fabric tensor of contact shear force component FT13, shape (steps,)

FT22 instance-attribute

FT22: ndarray

Fabric tensor of contact shear force component FT22, shape (steps,)

FT23 instance-attribute

FT23: ndarray

Fabric tensor of contact shear force component FT23, shape (steps,)

FT33 instance-attribute

FT33: ndarray

Fabric tensor of contact shear force component FT33, shape (steps,)

I1 instance-attribute

I1: ndarray

First invariant of stress, shape (steps,)

I2 instance-attribute

I2: ndarray

Second invariant of stress, shape (steps,)

I3 instance-attribute

I3: ndarray

Third invariant of stress, shape (steps,)

J2 instance-attribute

J2: ndarray

Second invariant of deviatoric stress, shape (steps,)

J3 instance-attribute

J3: ndarray

Third invariant of deviatoric stress, shape (steps,)

alpha instance-attribute

alpha: ndarray

Void ratio ratio, shape (steps, size, 3)

an instance-attribute

an: ndarray

Degree of fabric anisotropy for the contact normal force, shape (steps,)

ar instance-attribute

ar: ndarray

Degree of fabric anisotropy, shape (steps,)

at instance-attribute

at: ndarray

Degree of fabric anisotropy for the contact shear force, shape (steps,)

cached_num instance-attribute

cached_num: ndarray

cached number of integration points

chi instance-attribute

chi: ndarray

Bounding ratio, shape (steps, size)

contactVars cached property

contactVars: List[str]

Available contact variables

d2w cached property

d2w: ndarray

Second derivative of the work, shape (steps,)

d2wl cached property

d2wl: ndarray

Second derivative of the work of contacts, shape (steps, size)

data instance-attribute

data: List['StateVariable']

State variables

ddisp cached property

ddisp: ndarray

Displacement increment, shape (steps, size, 3)

ddispp cached property

ddispp: ndarray

Plastic displacement increment, shape (steps, size, 3)

deps cached property

deps: ndarray

Strain increment, shape (steps, 6)

depsa cached property

depsa: ndarray

Axial strain increment, shape (steps,)

depsd cached property

depsd: ndarray

General shear strain increment, shape (steps,)

depsp cached property

depsp: ndarray

Plastic strain increment, shape (steps, 6)

depspa cached property

depspa: ndarray

Axial plastic strain increment, shape (steps,)

depspd cached property

depspd: ndarray

General shear plastic strain increment, shape (steps,)

depspv cached property

depspv: ndarray

Volumetric plastic strain increment, shape (steps,)

depsv cached property

depsv: ndarray

Volumetric strain increment, shape (steps,)

dfn cached property

dfn: ndarray

Normal force increment, shape (steps, size)

dforce cached property

dforce: ndarray

Force increment, shape (steps, size, 3)

dfr cached property

dfr: ndarray

Shear force increment, shape (steps, size)

dfs cached property

dfs: ndarray

Shear force increment at the first direction, shape (steps, size)

dft cached property

dft: ndarray

Shear force increment at the second direction, shape (steps, size)

disp instance-attribute

disp: ndarray

Displacement for every integration point, shape (steps, size, 3)

dispp instance-attribute

dispp: ndarray

Plastic displacement for every integration point, shape (steps, size, 3)

dsig cached property

dsig: ndarray

Stress increment, shape (steps, 6)

dun cached property

dun: ndarray

Normal displacement increment, shape (steps, size)

dupn cached property

dupn: ndarray

Plastic normal displacement increment, shape (steps, size)

dupr cached property

dupr: ndarray

Plastic shear displacement increment, shape (steps, size)

dups cached property

dups: ndarray

Plastic shear displacement increment at the first direction, shape (steps, size)

dupt cached property

dupt: ndarray

Plastic shear displacement increment at the second direction, shape (steps, size)

dur cached property

dur: ndarray

Shear displacement increment, shape (steps, size)

dus cached property

dus: ndarray

Shear displacement increment at the first direction, shape (steps, size)

dut cached property

dut: ndarray

Shear displacement increment at the second direction, shape (steps, size)

e instance-attribute

e: ndarray

Void ratio, shape (steps,)

ec instance-attribute

ec: ndarray

Critical void ratio, shape (steps,)

eps instance-attribute

eps: ndarray

Strain, shape (steps, 6)

epsa instance-attribute

epsa: ndarray

Axial strain, shape (steps,)

epsd instance-attribute

epsd: ndarray

General shear strain, shape (steps,)

epsi cached property

epsi: ndarray

Strain after the first phase, shape (steps, 6)

epspi cached property

epspi: ndarray

Plastic strain after the first phase, shape (steps, 6)

epspq cached property

epspq: ndarray

Plastic strain exclude strain after the first phase, shape (steps,)

epspqa cached property

epspqa: ndarray

Axial plastic strain exclude strain after the first phase, shape (steps,)

epspqd cached property

epspqd: ndarray

General plastic shear strain exclude strain after the first phase, shape (steps,)

epspqv cached property

epspqv: ndarray

Volumetric plastic strain exclude strain after the first phase, shape (steps,)

epsq cached property

epsq: ndarray

Strain exclude strain after the first phase, shape (steps,)

epsqa cached property

epsqa: ndarray

Axial strain exclude strain after the first phase, shape (steps,)

epsqd cached property

epsqd: ndarray

General shear strain exclude strain after the first phase, shape (steps,)

epsqv cached property

epsqv: ndarray

Volumetric strain exclude strain after the first phase, shape (steps,)

epsv instance-attribute

epsv: ndarray

Volumetric strain, shape (steps,)

eta instance-attribute

eta: ndarray

Stress ratio, shape (steps,)

f instance-attribute

f: ndarray

Yield function value, shape (steps, size)

fb instance-attribute

fb: ndarray

Bounding force, shape (steps, size)

fci instance-attribute

fci: ndarray

Intrinsic size of yield surface, shape (steps, size)

feta instance-attribute

feta: ndarray

Contact force ratio, shape (steps,)

fn instance-attribute

fn: ndarray

Normal force for every integration point, shape (steps, size)

fncri cached property

fncri: ndarray

Normal force series for the critical state line

force instance-attribute

force: ndarray

Force for every integration point, shape (steps, size, 3)

fr instance-attribute

fr: ndarray

Shear force for every integration point, shape (steps, size)

frcri cached property

frcri: ndarray

Shear force series for the critical state line

fs instance-attribute

fs: ndarray

Shear force at the first direction for every integration point, shape (steps, size)

ft instance-attribute

ft: ndarray

Shear force at the second direction for every integration point, shape (steps, size)

negp instance-attribute

negp: ndarray

Negative mean stress, shape (steps,)

nintegration cached property

nintegration: int

Number of integration points

nsteps cached property

nsteps: int

Number of steps

p instance-attribute

p: ndarray

Mean stress, shape (steps,)

p0 instance-attribute

p0: ndarray

Size of the yield surface for the SaniSand model, shape (steps, size)

pcri cached property

pcri: ndarray

Mean stress series for the critical state line

phase instance-attribute

phase: ndarray

load phase index

q instance-attribute

q: ndarray

Deviatoric stress, shape (steps,)

qcri cached property

qcri: ndarray

Deviatoric stress series for the critical state line

sig instance-attribute

sig: ndarray

Stress, shape (steps, 6)

step cached property

step: ndarray

Step number

un instance-attribute

un: ndarray

Normal displacement for every integration point, shape (steps, size)

upn instance-attribute

upn: ndarray

Plastic normal displacement for every integration point, shape (steps, size)

upr instance-attribute

upr: ndarray

Plastic shear displacement for every integration point, shape (steps, size)

ups instance-attribute

ups: ndarray

Plastic shear displacement at the first direction for every integration point, shape (steps, size)

upt instance-attribute

upt: ndarray

Plastic shear displacement at the second direction for every integration point, shape (steps, size)

ur instance-attribute

ur: ndarray

Shear displacement for every integration point, shape (steps, size)

us instance-attribute

us: ndarray

Shear displacement at the first direction for every integration point, shape (steps, size)

ut instance-attribute

ut: ndarray

Shear displacement at the second direction for every integration point, shape (steps, size)

w instance-attribute

w: ndarray

Work, shape (steps, size)

__contains__ cached

__contains__(item) -> bool

Check if a state variable is available

__getattr__ cached

__getattr__(name: str) -> ndarray

Get state variables

PARAMETER	DESCRIPTION
name	A string specifies name of the state variable. It can end with a column number (1, 2, 3, 4, 5, 6) to specify the column of the state variable when it is a vector. TYPE: str

RETURNS	DESCRIPTION
array	An array of the state variable TYPE: ndarray

__getitem__ cached

__getitem__(item: str) -> ndarray

Get state variables

PARAMETER	DESCRIPTION
item	A string specifies name or an expression of the state variable parsed by sympy. The expression can contain any of the available state variables, and it can end with a column number (1, 2, 3, 4, 5, 6) to specify the column of the state variable when it is a vector. TYPE: str

RETURNS

DESCRIPTION

array

An array of the state variable, the shape of the array depends on the type of the state variable and the arguments specified in the name and index: 1D array (shape (steps,)): the state variable is a scalar; the state variable is a vector, is not a contact variable, and the column number is specified in the name. 2D array (shape (steps, ndim)): the state variable is a vector, is not a contact variable, and the column number is not specified in the name. 2D array (shape (steps, integration size)): the state variable is a contact variable (force, disp), the column number is specified in the name. 3D array (shape (steps, integration size, ndim)): the state variable is a contact variable (force, disp), the column number is not specified in the name. TYPE: ndarray

__hash__

__hash__() -> int

Get the hash of the state variables exporter, which is the hash of the data and phase attributes.

abaqusStateVariableNames classmethod

abaqusStateVariableNames(
    contact_type: str | None = None, size: int = 37, reverse: bool = False
) -> dict[str, str]

The state variable names for the Abaqus subroutine, a dictionary of ("SDV{i}", name) pairs. If reverse is True, the dictionary is reversed to {name: "SDV{i}"} pairs.

fromAbaqusStateVariables classmethod

fromAbaqusStateVariables(
    data: Union[Iterable, str, PathLike],
    contact_type: str | None = None,
    *,
    size: int = 37,
    phase_column: str = "Step"
) -> "SVExporter"

Create state variables exporter by a data file exported from an Abaqus output database, data is a pandas DataFrame or a csv file with columns of names like SDV{i}. A column with name Step is required to specify the load phase or any other column name specified by phase_column, if the column is not available, the phase will be set to 0.

get

get(
    var: str,
    *,
    phase: int | slice | Iterable[int] = slice(None),
    step: int | slice | Iterable[int] = slice(None),
    idx: int | slice | Iterable[int] = slice(None),
    col: int | slice | Iterable[int] = slice(None),
    smooth_variables: list[str] | None = None
) -> Union[ndarray, float]

Get state variables

PARAMETER	DESCRIPTION
var	A string specifies name or an expression of the state variable parsed by sympy. The expression can contain any of the available state variables, and it can end with a column number (1, 2, 3, 4, 5, 6) to specify the column of the state variable when it is a vector. TYPE: str
phase	An integer or a slice indicates index of the phase. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
step	An integer or a slice indicates index of the step, noted that the step index is the relative step index to the phase if phase is specified. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
idx	An integer or a slice indicates index of the integration point for contact variables. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
col	An integer or a slice indicates index of the column for variables with multiple columns, this argument will be ignored if the variable has only one column or the column index is already specified in var. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
smooth_variables	A list of state variable names to be smoothed, by default None. TYPE: list[str] | None DEFAULT: None

RETURNS	DESCRIPTION
array	An array or a float of the state variable TYPE: ndarray or float

indexOf

indexOf(
    phase: int | slice | Iterable[int] = slice(None),
) -> Union[ndarray, int, slice]

Get the indices of the corresponding steps belonging to a phase or phases

isContactVariable

isContactVariable(var: str) -> bool

Check if a state variable is a contact variable

toDataFrame

toDataFrame(
    includes: Iterable[str] | None = None,
    excludes: Iterable[str] = (),
    *,
    phase: int | slice | Iterable[int] = slice(None),
    step: int | slice | Iterable[int] = slice(None),
    idx: int | slice | Iterable[int] = slice(None),
    col: int | slice | Iterable[int] = slice(None),
    set_columns: bool = False
)

Convert state variables to a pandas DataFrame

PARAMETER	DESCRIPTION
includes	An iterable of state variable names to be included, by default None, which means only stress and strain state variables will be included. TYPE: Iterable[str] DEFAULT: None
excludes	An iterable of state variable names to be excluded, by default (), which means no state variable will be excluded. TYPE: Iterable[str] DEFAULT: ()
phase	Filters for the state variables, see :meth:get for details. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
step	Filters for the state variables, see :meth:get for details. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
idx	Filters for the state variables, see :meth:get for details. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
col	Filters for the state variables, see :meth:get for details. TYPE: int | slice | Iterable[int] DEFAULT: slice(None)
set_columns	Set the column names of the DataFrame, by default False. TYPE: bool DEFAULT: False

to_csv

to_csv(
    filename: PathLike | str,
    includes: Iterable[str] | None = None,
    excludes: Iterable[str] = (),
    *,
    phase: int | slice | Iterable[int] = slice(None),
    step: int | slice | Iterable[int] = slice(None),
    idx: int | slice | Iterable[int] = slice(None),
    col: int | slice | Iterable[int] = slice(None),
    set_columns: bool = False,
    **kwargs
)

Save state variables to a csv file

PARAMETER	DESCRIPTION
filename	The filename to save the state variables. TYPE: PathLike or str
includes	Arguments for :meth:toDataFrame. TYPE: Iterable[str] | None DEFAULT: None
excludes	Arguments for :meth:toDataFrame. TYPE: Iterable[str] | None DEFAULT: None
phase	Arguments for :meth:toDataFrame. TYPE: Iterable[str] | None DEFAULT: None
step	Arguments for :meth:toDataFrame. TYPE: Iterable[str] | None DEFAULT: None
idx	Arguments for :meth:toDataFrame. TYPE: Iterable[str] | None DEFAULT: None
col	Arguments for :meth:toDataFrame. TYPE: Iterable[str] | None DEFAULT: None
set_columns	Set the column names of the DataFrame, by default True. TYPE: bool DEFAULT: False
kwargs	Other arguments for :meth:pandas.DataFrame.to_csv. DEFAULT: {}

get_include

get_include(includes: str | None = None) -> str

Return the directory containing the C/C++ header files.

PARAMETER	DESCRIPTION
includes	Additional include directories to add, separated by os.pathsep. If None, the default include directories are used. TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
include_dir	The directory containing the C header files TYPE: str

register_model

register_model(
    model_name: str,
    model_class: type,
    *,
    type: Literal[
        "elastoplastic", "micromechanical", "micromechanical_contact"
    ] = "elastoplastic"
)

Register a model to the library.

PARAMETER	DESCRIPTION
model_name	The name of the model to add. This should be a unique identifier for the model type. TYPE: str
model_class	The class of the model to add. TYPE: type
type	The type of the model to add. This should be one of "elastoplastic", "micromechanical", or "micromechanical_contact". Default is "elastoplastic". TYPE: Literal['elastoplastic', 'micromechanical', 'micromechanical_contact'] DEFAULT: 'elastoplastic'

visualize_calibration

visualize_calibration(
    model_type: Union[
        str | PathLike,
        AvailableModels,
        AvailableMicromechanicalModels,
        AvailableContactModels,
    ],
    calibration_file: str | PathLike,
    *,
    options: dict[str, ...] | None = None,
    parameters: dict[str, float] | None = None,
    check_fitness: bool = True,
    experiments: dict | None = None,
    experiment_file: str | PathLike | None = None,
    experiment_filter: dict | None = None,
    plot_method: Literal[
        "plot",
        "plotof",
        "plotExperiments",
        "plotSimulations",
        "plotComparisons",
    ] = "plotComparisons",
    plot_args: tuple | None = None,
    **plot_kwargs: Unpack[PlotOfOptions]
)

Visualize the results of a calibration.

PARAMETER	DESCRIPTION
model_type	Model type to use for visualization. TYPE: Union[str | PathLike, AvailableModels, AvailableMicromechanicalModels, AvailableContactModels]
calibration_file	Path to the calibration file. TYPE: str or PathLike
options	Additional options to set for the model. These will override any options set in the calibration file. TYPE: dict DEFAULT: None
parameters	Additional parameters to set for the model. These will override any parameters set in the calibration file. TYPE: dict DEFAULT: None
check_fitness	Whether to check the fitness of the calibration before visualizing. If True, a warning will be raised if the calculated fitness does not match the fitness reported in the calibration file. Default is True. TYPE: bool DEFAULT: True
experiments	Additional experiments to include in the visualization. The keys should be the experiment names, and the values should be Experiment objects. If None, only the experiments included in the calibration file will be used TYPE: dict DEFAULT: None
experiment_file	Path to a file containing additional experiments to include in the visualization. The file should be in a format that can be read by the Model.loadExperiments() method. TYPE: str or PathLike DEFAULT: None
experiment_filter	Experiment filter to filter the experiments to include in the visualization. Keyword arguments to pass to the Model.filterExperiments() method, an additional args argument can be passed to Model.filterExperiments() as a positional argument. TYPE: dict DEFAULT: None
plot_method	Method to use for plotting the results. Should be one of "plot", "plotof", "plotExperiments", "plotSimulations", or "plotComparisons". Default is "plotComparisons". TYPE: Literal['plot', 'plotof', 'plotExperiments', 'plotSimulations', 'plotComparisons'] DEFAULT: 'plotComparisons'
plot_args	Positional arguments to pass to the plotting method. If None, all x-y pairs from the experiments will be used. TYPE: tuple DEFAULT: None
plot_kwargs	Keyword arguments to pass to the plotting method. TYPE: Unpack[PlotOfOptions] DEFAULT: {}