Example usage

New constitutive model

If you've been given a model already, and want to tweak it to use a new constitutive model the best way to go about this is to add a new material point class. The CLOS system of common lisp is very powerful and easy to (ab)use and a nice tutorial can be found on the coookbook Cookbook CLOS page.

Lets say you've been given a problem that is linear elastic, and want to add a new type of plasticity to it, for instance a Reuleaux plasticity model. The Reuleaux plasticity model has three parameters:

• Cohesion
• Friction angle
• Shape factor $\rho_e$

Adding the particle class

Since this is a elasto-plastic model our class should inherit from the elastic class (particle-elastic). Using the CLOS system, a class is defined with defclass like so:

(defclass particle-reuleaux (particle-elastic)
  ((coheasion
        :accessor particle-cohesion
        :initarg :cohesion
        :initform 0d0)
   (friction-angle
        :accessor particle-friction-angle
        :initarg :friction-angle
        :initform 0d0)
   (rho-e
        :accessor particle-rho-e
        :initarg :rho-e
        :initform 0.5d0)))

We can see the three parameters we've added coheasion,friction-angle,rho-e however we can unpack this down and explain what's going on

(defclass ;;<--------------------- defining a new class everything goes in brackets ()
      particle-reuleaux ;; <------ The name of our new class
    (                           ;; This first list is a parent classes
     particle-elastic           ;; We want to inherit the elastic behaviour so we include this here
     ...                        ;; We could add more classes but we don't need to
     )                          ;; We close the list as we normally do in lisp
  (                             ;; The next list is for all the "slots" we are going to add these are the parameters the class owns
                                ;; Each slot definition is just a list
   (coheasion ;; <---------------- this is the name of the slot
    :accessor particle-cohesion ;; This accessor is how you "Get" or "Set" the value from a class
                                ;; i.e. (print (particle-cohesion mp)) will get the value from the mp object and print it
    :initarg :cohesion ;;<-------- this defines the shorthand for when we initalise objects, make it short but meaningful
    :initform 0d0               ;; The initial form is the default value this slot takes
    )                           ;; its just a list so close it back up
                                ;; and again with the other two slots we do the same thing
   (friction-angle
    :accessor particle-friction-angle
    :initarg :friction-angle
    :initform 0d0)
   (rho-e
    :accessor particle-rho-e
    :initarg :rho-e
    :initform 0.5d0)))           ;; Make sure to close up all the parentheses! 

So the general simple form is:

(defclass new-class-name (parent-1 parent-2)
  ((slot-name
    :initarg :argument-name
    :accessor particle-slot-name
    :initform default-value)))

There's loads of other features but these are the most general ones. The initargs help us initialise material points later:

(make-instance 'particle-reulaux
               :friction-angle (/ pi 6)
               :coheasion 100d3 ;; 100 x 10^3
               :rho-e 0.6d0)
             ;;^^^^^^^ -> the names we gave for the initarg are what we put before the value we want to initialise the slot with

Setting up the constitutive function

The next part is setting up the method that we want to get called when anybody tries to update a material points stress. The constitutive model is called with a particle, a strain (trial) and a timestep. Assuming that you've go a function reuleaux that takes in: (strain, Young's modulus, Possion's ratio, Friction angle, Cohesion, rho-e) and returns just the elastic strain (elastic-strain) we can make use of the linear-elastic function in cl-mpm/constitutive to calculate the final stress which we return.

(defmethod cl-mpm/particle:constitutive-model ((mp particle-reuleaux) strain dt)
  (setf
   (cl-mpm/particle:mp-strain mp)
   (reuleaux strain
             (cl-mpm/particle:particle-E mp)
             (cl-mpm/particle:particle-nu mp)
             (particle-friction-angle mp)
             (particle-cohesion mp)
             (particle-rho-e mp)))
  (cl-mpm/constitutive:linear-elastic
   (cl-mpm/particle:mp-strain mp)
   (cl-mpm/particle:particle-E mp)
   (cl-mpm/particle:particle-nu mp)))

Note because the linear elastic particle and its accessors are in the cl-mpm/particle package we have to specify this with cl-mpm/particle: before calling them. And the linear-elastic constitutive model is held in the cl-mpm/constitutive package so it needs to be qualified as well. Note that this update scheme is adjusting the particles internal (particle-strain mp) measure and then calculating that - the constitutive models may statefully change the material point passed in!