ComputeTool

The ComputeTool object is used to perform calculations that may be re-used by various modules. Unlike a Module, a ComputeTool is assumed to perform its functions independently, and so does not require any data sharing paradigm beyond passing arguments into its methods. All ComputeTool objects are owned by Simulation. When a Module wants to create or release a ComputeTool it calls a method of Simulation to do so.

When to use a ComputeTool

The ComputeTool provides services for free that a simple function or user defined object does not. There are also services that are not provided, being reserved for Module objects. The basic characteristics are:

  1. Easy management of input file and restart file interactions

  2. Easy access to OpenCL kernel functions.

  3. Management of allocation and de-allocation of resources, accounting for the possibility of multiple references to the tool.

  4. No data sharing. A ComputeTool does not participate in publisher-consumer data movement, and one ComputeTool cannot contain another.

  5. No direct invocation within the main simulation loop. All data processing has to be initiated by a Module which has a pointer to the ComputeTool.

Example

A straightforward example of a module that uses a ComputeTool inheritance tree is the FieldSolver module in fieldSolver.h and FieldSolver.cpp. This FieldSolver base class exists largely to manage various types of elliptical solvers. The elliptical solver tools themselves are implemented in elliptic.h and Elliptic.cpp.

Implementing a ComputeTool

Declaration

When implementing a new ComputeTool, first carry out the following.

  1. In computeTool.h, introduce a new tw::tool_type element. This is a label for the type of tool.

  2. In ComputeTool.cpp, add a case to the CreateObjectFromType method for the new type.

  3. In an appropriate header file, derive the new type from ComputeTool.

  4. In an appropriate source file, implement the ComputeTool.

    • The tool can implement whatever methods are desired. A function that moves data forward by one time level is conventionally called Advance.

    • Further implementation details follow.

Association with Module

Carry out the following for any Module that wants to use the tool.

  1. In the Module declaration, declare a pointer to the tool. Polymorphism may be used to whatever extent is desired.

  2. In the constructor, set the pointer to NULL.

  3. In the destructor, if the pointer is not NULL, call owner->RemoveTool with the pointer as the argument.

Input File Support

If you want the tool to be accessible from the input file, carry out the following steps.

  1. In the tool’s constructor define the input file directives. For each directive make one call to directives.Add(std::string&,tw::input::Directive*).

  2. Add an entry to the hash table returned by Map in ComputeTool.cpp. This connects the directive key with the tw::tool_type.

  3. In the VerifyInput method of each Module that wants to use the tool:

    • Search the moduleTool vector for a compatible tool, and copy the dynamically typecast compatible pointer to your pointer.

    • If no compatible tool is found, either throw an error, or create a default tool using owner->CreateTool.

  4. If you need to set the tool’s member variables based on module data, it is safest to do this in the Initialize method, since this is called only after all modules have exchanged resources.

Tip

If you want to create a tool exclusively for the use of a particular module, and there is no need for input file or restart file interaction, you can simply create it in the module constructor, and remove it in the module destructor.

Tip

If implemented correctly, tools are ready to be used by the time Module::Initialize is called.

Restart File Support

As of version 4.0, only time varying quantities need to be checkpointed (no need to store constants or structural information). To support restarting a tool, carry out the following steps.

  1. Override the tool’s ReadCheckpoint method. Call the inherited ReadCheckpoint method first. Then read any necessary data from the restart file.

  2. Override the tool’s WriteCheckpoint method. Call the inherited WriteCheckpoint method first. Then write any necessary data to the restart file.

  3. Verify that ReadCheckpoint and WriteCheckpoint access the data in the same order.

Best Practices

  1. Avoid making the tool the owner of heavyweight data. Instead pass such data to member functions by reference.

  2. Keep self-contained, i.e., avoid using references to modules or other objects in the containment hierarchy. If this seems unavoidable consider using a Module.