Using Python with MPoint

This section gives an example of using a Python program to interact with MPoint. In this example we create a simple MPoint model and use Python to explore the material point properties and model response.

First we import the c itasca module with the import statement. The itasca module defines the interaction between Python and MPoint. We import the itasca module as the shortened name it. We also import the vec3 type for working with 3D vectors.

import itasca as it
from vec import vec3

We are going to create some material points to show features of the Python scripting. The itasca.command function is used to issue a series of MPoint commands.

These commands create a new model, define the domain, and generate material points. The triple quotes are used to define a multi-line string.

it.command("""
model new
model domain extent -1 1
mpoint node spacing 1.0
mpoint generate range position -0.5 -0.5 -0.5 0.5 0.5 0.5
""")

Working with MPoint Material Points

We can get the number of material points by using the itasca.mpoint.count function.

it.mpoint.count()

output:

8

The itasca module defines functions and classes for interacting with the MPoint model. Some of these functions return objects,

mp = it.mpoint.find(1)
print(mp)

output:

<itasca.mpoint.MPMPoint object at 0x0000023B95620130, ID : 1>

Here itasca.mpoint.find returns an MPMPoint object for the material point with id 1. This object is assigned to the Python variable mp. The MPMPoint object has many methods, for example

mp.pos()

output:

vec3(( -2.500000e-01, -2.500000e-01, -2.500000e-01 ))

The variable mp is an MPMPoint object which represents a single material point. pos (itasca.mpoint.MPMPoint.pos) is a method of this object that returns the material point position.

Note

The itasca.mpoint.MPMPoint.pos method returns a length three vector represented as a vec3 object. See c vec module for more information about vec3 objects and working with vectors in Python.

print("material point", mp.id(), "at", mp.pos())

In Python the for statement is used to iterate over sequences of things,

total_mass = 0.0
for mp in it.mpoint.list():
    total_mass += mp.mass()

In this example the for statement is used to loop over all the MPoint material points. During each loop the variable mp is a different MPMPoint object.

print(total_mass)

Let’s find a material point near a specific location

mp = it.mpoint.near((-0.475, -0.475, -0.475))
print(mp.id())

output:

1

Creating Material Points

Material points can be created individually using the mpoint create command.

it.command("""
mpoint create position 0.9,0.9,0.9 volume 0.01
""")

mp_new = it.mpoint.find(1)
print("New material point at:", mp_new.pos())

output:

New material point at: vec3(( -2.500000e-01, -2.500000e-01, -2.500000e-01 ))

Working with MPoint Material Point Properties

We can assign constitutive models and properties to material points.

it.command("""
model large-strain on
mpoint cmodel assign elastic
mpoint property density 2000 young 1e5 poisson 0.3
model gravity 0 0 -10
""")

The props method (itasca.mpoint.MPMPoint.props) returns the material point constitutive model properties as a Python dictionary object.

mp.props()

output:

{}

To access individual properties, use the prop method:

mp.prop('young')

output:

99999.99999999999

Material point properties can be set with the set_prop method:

mp.set_prop('young', 20000)
print(mp.prop('young'))

output:

19999.999999999996

Working with MPoint Material Point State

Material points have state variables such as displacement, velocity, stress, and strain.

mp.disp()
mp.velocity()
mp.stress()
mp.strain()

Displacement can be set and modified:

mp.set_disp((0, 1, 0))
print(mp.disp().mag())

it.command("""
mpoint initialize displacement multiply 2
""")
print(mp.disp().mag())

output:

1.0
2.0

Working with MPoint Groups

Groups are used to create a list of MPoint material points. Here we create groups of material points representing different regions of the model.

it.command("""
mpoint group 'test1' range position -0.5 -0.5 -0.5 0 0 0
mpoint group 'test2' slot 'bigger' range position -0.5 -0.5 -0.5 0 0.5 0.5
""")

We can query if a material point is part of a group using the in_group method.

for mp in it.mpoint.list():
    if mp.pos_x() < 0 and mp.pos_y() < 0 and mp.pos_z() < 0:
        if mp.in_group('test1'):
            print("MP", mp.id(), "is in group test1")

output:

MP 1 is in group test1

Material points can be added to groups programmatically:

for mp in it.mpoint.list():
    if mp.pos_x() < 0:
        mp.set_group('region_left')
        if mp.in_group('region_left'):
            print("MP", mp.id(), "added to region_left")

output:

MP 1 added to region_left
MP 3 added to region_left
MP 5 added to region_left
MP 7 added to region_left

Working with MPoint Material Point Extra Variables

MPoint material points have extra variables that allow data to be associated with the material point. Python programs can read and write extra variables.

it.command("""
mpoint extra 1 [vector(1,1,1)]
""")

for mp in it.mpoint.list():
    print("MP", mp.id(), "extra(1):", mp.extra(1))
    mp.set_extra(2, "custom_data")
    print("MP", mp.id(), "extra(2):", mp.extra(2))

output:

MP 1 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 1 extra(2): custom_data
MP 2 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 2 extra(2): custom_data
MP 3 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 3 extra(2): custom_data
MP 4 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 4 extra(2): custom_data
MP 5 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 5 extra(2): custom_data
MP 6 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 6 extra(2): custom_data
MP 7 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 7 extra(2): custom_data
MP 8 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 8 extra(2): custom_data
MP 9 extra(1): vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 9 extra(2): custom_data

Extra variables are stored in the model save file, allowing Python data to persist with the model state.

Working with MPoint Material Point Forces

Applied forces can be set on material points:

for mp in it.mpoint.list():
    if mp.pos_x() < 0:
        mp.set_force_app((1, 1, 1))
        print("MP", mp.id(), "applied force:", mp.force_app())

output:

MP 1 applied force: vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 3 applied force: vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 5 applied force: vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))
MP 7 applied force: vec3(( 1.000000e+00, 1.000000e+00, 1.000000e+00 ))

Array-style Access to Material Point Data

For efficient bulk operations, material point data can be accessed as numpy arrays:

import numpy as np

ma = it.mpoint.mpmpointarray
print(type(ma.density()))
print(type(ma.pos()))
print(type(ma.velocity()))
print(type(ma.stress()))

output:

<class 'numpy.ndarray'>
<class 'numpy.ndarray'>
<class 'numpy.ndarray'>
<class 'numpy.ndarray'>

Array data can be read and written efficiently:

ma.set_density(ma.density() * 1.1)
print("Updated densities:", ma.density())

output:

Updated densities: [2200. 2200. 2200. 2200. 2200. 2200. 2200. 2200. 2200.]

Mechanics Information

Global mechanics information can be queried:

it.mpoint.mech_ratio_avg()
it.mpoint.mech_ratio_max()
it.mpoint.mech_unbal_max()
it.mpoint.mech_ratio_local()

Material Point Volume and Mass

Individual material point properties:

mp = it.mpoint.find(1)
print("Volume:", mp.vol())
print("Mass:", mp.mass())
print("Density:", mp.density())

output:

Volume: 0.125
Mass: 275.0
Density: 2200.0

Material Point Deformation

The deformation measure can be queried:

for mp in it.mpoint.list():
    print("MP", mp.id(), "deformation:", mp.deformation())

output:

MP 1 deformation: 1.0
MP 2 deformation: 1.0
MP 3 deformation: 1.0
MP 4 deformation: 1.0
MP 5 deformation: 1.0
MP 6 deformation: 1.0
MP 7 deformation: 1.0
MP 8 deformation: 1.0
MP 9 deformation: 1.0

Pore Pressure

Pore pressure can be set and queried:

mp.set_pp(1.4)
print("Pore pressure:", mp.pp())
mp.set_pp_fix(True)
print("PP fix enabled:", mp.pp_fix())

output:

Pore pressure: 1.4
PP fix enabled: True

Summary

This example demonstrated:

  • Creating and managing material points

  • Setting constitutive models and properties

  • Working with groups for spatial selection

  • Accessing and modifying state variables

  • Using extra variables for custom data

  • Array-style bulk data access

  • Querying mechanics information

  • Pore pressure handling

For complete API documentation, see:

Example File

The source code for this example is python_mpac.py