Writing a Custom Task

This page explains how to create a new custom task and integrate it into NairnMPM. Custom tasks can be used to add many new features to the code, including new ways to export results for visualization.

Basic Steps

The first steps create the task and allow it to be used in calculations

• Create a new source code class that inherits from the CustomTask class (or a subclass of that class).
• Create instance of this new task in MPMReadHandler::myStartElement()when an input file wants to use the new task:
  • See code section that handles the Schedule element
  • Create new instance of your task as determined by the name attribute of Schedule element
  • This change should be the only change made to the core code.
• Support methods listed below (as needed) in the new custom task. Most methods return the nextTask because the calling code uses it when it loops over all custom tasks. Any methods that are not needed can be omitted because the CustomTask class provides place-holder methods that simply returns the nextTask. Custom tasks are done at the end of each time step and handled by the RunCustomTasksTask class.

Task Parameters

If the custom task has parameters, implement them by reading them with:

char *CustomTask::InputParam(char *pName,int &input,double &gScaling)

Check the parameter name in pName. If it matches a defined task parameter name set input to the kind of parameter and return a pointer to the class variable for that parameter. If pName is not a valid parameter name return NULL. Note that this method does not return nextTask because it needs to return a pointer. Custom tasks support three types of parameters - doubles, ints, and text strings. For doubles and ints, set input to DOUBLE_NUM or INT_NUM, respectively, and return pointer to the double or int variable to receive value for that parameter. For text strings, set input to TEXT_PARAMETER and return any non-NULL pointer. When the text string is read, this custom tasks will be called through the SetTextParameter() function.
    The gScaling parameter is used by old custom tasks to allow them to work with both Legacy units and the new Consistent units mode. New custom tasks should not need to use this parameter. They should assume consistent units.

void CustomTask::SetTextParameter(char *value)

To allow text parameters, the InputParam() function should set input to TEXT_PARAMETER. This setting will be immediately followed by a call to this method where the text for the parameter to be processed is in value. Note that this function does not transfer the name of the parameter. Thus, the class may need to set some variable in InputParam() to allow this method to know which parameter is being processed. Values of text parameters are guaranteed to be called immediately after the InputParam() call that selects them. If the text parameter is not valid, this method can call ThrowSAXException() to signal the error. Note that this method does not return nextTask

Initialize

This method is called once at beginning of the entire MPM analysis:

CustomTask *CustomTask::Initialize()

Do any initialization and print info about the task using cout. Anything printed will by in the custom tasks section of the results file.

MPM Time Step Tasks

In each time step, a custom task is called through various methods. Your new task can implement those that are needed.

Prepare Custom Task

This method is called just before custom tasks are started:

CustomTask *MyTask::PrepareForStep(bool &doExtraps)

Initialize variables used by the task in the current time step. If the task needs extrapolations to the grid, set doExtraps to TRUE. Note that extrapolations to the grid in custom tasks are not done in parallel. Tasks that need to extrapolate to the grid should normally only be for periodic tasks, such as archiving grid results. Extrapolations that are done every time step might impact performance. If such tasks become essential, it will be better to incorporate them in the code as an actual (and parallel) task instead of a custom task. The custom task approach, however, can still be useful for developing a new feature.

Custom Extrapolatlions

The following methods are in a loop which allows a custom task to extrapolate some property to the grid (see VTKArchive Custom Task code for example of a task that uses loop extrapolation). Note there is no automatic handling for looping over particles, but a task can easily implement that loop on its own (see AdjustTimeStep Custom Task code for example of a task that implements a particle loop).

CustomTask *MyTask::BeginExtrapolations(void)

Called once before the extrapolation loop begins. Initialize any required extrapolation variables.

CustomTask *MyTask::NodalExtrapolation(NodalPoint *ndmi,MPMBase *mpnt,short vfld,int matfld,double wt)

Called repeatedly in the loop for each particle/node pair. vfld is the velocity field, matfld is material velocity field (when in multimaterial mode), and wt is the weight (or mass times shape function). You can use this method to extrapolate particle data to the grid.

CustomTask *MyTask::EndExtrapolations(void)

Called once when extrapolations are over. This method should free anything allocated during the extrapolations or to do some calculations.

Custom Task Calculations

This method is the usually the main part of any custom task:

CustomTask *MyTask::StepCalculation(void)

Do the desired calculations. The code will have access to all global variables.

Custom Task Clean Up

This method is called at the end of the time step:

CustomTask *MyTask::FinishForStep(void)

You should free up any memory still allocated by the task.