Creating a Constitutive Model coupled with an Active Tension Model

Overview

The Active Tension Model (ATM) can be coupled with the Constitutive Model (CM) through the use of time-dependent variables and update variables in the Constitutive Model Editor. Each time-dependent variable in CM must have a corresponding state variable of the same name in ATM. Each update variable in CM must have a corresponding update variable of the same name in ATM. These are the basic minimum requirements to be able to compile and use an active tension model in a biomechanics problem. ATM is defined separately from CM, but does not need to be compiled separately, since the use of update variables and time-dependent variables in CM allows ATM to be compiled together into the same module as CM.

When no update variables or time-dependent variables are defined in CM, the model is only a passive model. When at least one of these variables are present, the model becomes an active model.

Step-by-step example

This example model does nothing meaningful and is not intended to define a complete working model. The steps below serve only to explain the technical aspects of setting up a Constitutive Model coupled with an Active Tension model and show how the two are integrated in Continuity. The following steps are more or less what it will take to setup a model from scratch.

  1. Biomechanics→Edit→Constitutive Model…

  2. From the list of models, select << add new model >> and then click the Edit equations tab

  3. Notice the four independent variables and one dependent variable (stress) available by default. One of the independent variables is t, time, which will probably only be used if Active Tension is used. Let’s insert a time-dependent variable into the list before stress. Select t (to insert at that position), and click Insert Variable. Change the name to time_var and change the type to time dependent variable. Note that the equation box is grayed out with this variable type, because the values for time-dependent variables are calculated from their derivatives defined in ATM. These derivatives are then used in CM to calculate the updated values of time-dependent variables using the Forward-Euler method. The position of the first time-dependent variable in the list of variables in CM marks the time when ATM is called. Finally, these time-dependent variables can be used to calculate active tension in CM, and stress can be updated with active components.

  4. Let’s try to view the Fortran source code of what we have so far. Click on the View code tab. Oh no! Continuity should have generated an error that there is no corresponding state variable found in ATM for the time-dependent variable we added. If any update variables or time-dependent variables are present in CM, then their counterparts must also be present in ATM. Without this requirement, the model and its equations can only be saved and reloaded, but you cannot compile the model, nor view its Fortran source code. But we do want to compile right now, so let’s fix this problem… (you can leave the Constitutive Model Editor open, don’t close it)

  5. Biomechanics→Edit→Active Tension Model…

  6. From the list of models, select << add new model >> and then click the Edit equations tab

  7. By default, two variables are present for new models: an independent variable t representing time and an update variable SL representing sarcomere length. Add three more variables to the list by clicking the Insert Variable button three times. Change the name and type of these three new variables to be like so:

    • Name

      Type

      const

      constant

      temp

      temporary

      time_var

      state
  8. Change the new variables’ equations like so:

    • Select the const variable and from the menu select Insert→Template. Change the value of const to whatever you like. Optionally, change the description to something else if you like.

    • Select the temp variable and again insert a template. Just change the equation to be temp = <param1>+<param2>

    • Select time_var and again insert a template. Change the derivative to t * temp

  9. Click on the Set Parameters tab. Notice that there are three parameters which we did not define: delta_t, sl_cur, and sl_old. These can be left alone (and any changes to these parameters here will have no effect in the model). These parameters are automatically generated if the ATM contains any update variables (and like update variables in ATM, these are present for algorithmic purposes) You can edit the parameters <param1> and <param2>. As we shall see in the following steps, these parameters are also available directly from the Constitutive Model Editor for models that use Active Tension.

  10. Press Ctrl+s to save this model’s equations. Then click on the Submit tab and then click the Submit button to save this Active Tension Model for the problem. Now let’s get back to our Constitutive Model.

  11. In the Constitutive Model Editor, go back to the Edit equations tab and then again try clicking on the View code tab. This time, the source should be generated. But before we compile, let’s add some more equations to this model. Go back to Edit equations.

  12. Select time_var to set the insertion position for new variables. Let’s import some variables from Active Tension. From the menu bar, select Insert→Active Tension Variables. Notice that the variables list on the left is now overlaid with a list of variables from Active Tension. Also note that time_var is not present in this list because we have already added it manually to the CM variables list. Let’s insert all three AT variables in this list into our CM model. You can select by holding down the mouse button to select a range, or hold down Ctrl to select noncontiguous ranges or items. If a single item is selected from this list, the description, type, and equation will be updated from the defined Active Tension equations. Now, select all three variables in the list and click the Add selected button. Click around the newly added variables, and note how the equation box becomes:

    • blank and editable for update variable types

    • grayed out for time-dependent variable types

    • auto-filled for constant and temporary variable types, using the same equation as defined in Active Tension

    Note:: It is important to keep in mind the position of the first time-dependent variable relative to the positions of the update variables in list of CM variables. As mentioned earlier, in the sequence of equations generated, the call to the ATM is made at the point of the first time-dependent variable in CM. Thus, in a typical case, all update variables should be placed before the first time-dependent variable in the list. Otherwise, they might not get properly updated. If Continuity detects this is the case, you will be given a warning but still allowed to continue.

  13. Remember that there were two Active Tension parameters used in the equation for temp. Confirm that by selecting temp from the list. To use parameters from Active Tension in the CM equations, simply use them like any other parameter. If the model is detected to be an active model, then all parameters used will be first searched for in Active Tension, and then in CM. Thus, two different parameters of the same name (one in ATM and one in CM) cannot be used together when coupling models like this.

  14. Select stress from the list. Change stress(1,1) by setting it equal to stress(1,1) = time_var+temp*<param3>.

  15. Click on the Set parameters tab. Note that none of the parameters from Active Tension are listed here, since their values are defined in (and fetched from) the Active Tension Model. Only param3 is shown here, since it belongs to the CM.

  16. You can view the code by clicking the View code tab. Now let’s try to compile this.

    • Click on the Compile tab

    • Click the Compile button. If all goes well, the status should indicate success

Sample Model

Load any one of the three active_cubic_unloaded_canine*.cont6 problem files under the pcty/examples/biomechanics18 directory of your Continuity installation. This problem is a simple cube that uses the Rice 2008 canine active tension model included in Continuity by default. Open the Constitutive Model Editor. Here you will find an update variable named SL, whose equation can be edited. Now open the Active Tension Model Editor, where you will find an update variable of the same name (SL). Note that the equation box is grayed out. Update variables are present in the Active Tension Model only for integration and algorithmic purposes, so you should not need to edit them here. However, you need to ensure that for every update variable in CM, there is also an update variable of the same defined in ATM.

Also note the four time-dependent variables XBprer, XBpostr, xXBprer, and xXBpostr in CM. These correspond to state variables of the same name Active Tension Model Editor. For these, the situation is somewhat reversed: the equation box is grayed out in CM but editable in ATM. In ATM, the equation box should set d[SV]_dt equal to something, where [SV] is the name of the state variable.

Now, look at the equation for the T_a variable in CM, which is a temporary variable type representing active tension calculated from the four time-dependent variables (among others). The subsequent equations are to calculate active stress. Finally, look at the equations for stress. The first set of equations calculate passive stress. The latter set of equations add the active components to stress that is calculated from T_a.

You can run this biomechanics problem for about 100 time steps to see how the deformed cube looks.