interaction_oct_m Module Reference

This module defines the abstract interaction_t class, and some auxiliary classes for interactions. More...

Detailed Description

This module defines the abstract interaction_t class, and some auxiliary classes for interactions.

When executing two or more coupled iterative algorithms there needs to be a mechanism for the algorithms to exchange the information that couples them. In this framework, this is done by the interaction class and we call the information to be exchanged "couplings". An interaction connects two systems, which is the name given to the class that executes the algorithms and stores their internal state (see the system_t class for more details about systems).

Although the exchange of couplings between two systems usually happens in both directions, this is not always a symmetric operation. Therefore, the choice was made to split interactions between two systems into uni-directional interactions. This in turn means that the interactions have a well defined source (causing the interaction) and a target system, which is affected by the interaction:

The flow of information goes from the source to the target and the interaction is "owned" by the target. That means that, in the way systems and interactions are implemented, the target is aware of the interactions that affect it, but the source does not store any information about the interactions it needs to provide information to. Instead, during the algorithm execution, the source will receive requests to provide specific quantities it knows about to an interaction. Those quantities are the couplings.

In some cases, systems can require information at specific iterations that does not come from the execution of another algorithm. For example, this information could be a prescribed mathematical expression or data read from a file. Because of this, it is convenient to introduce the concept of "interaction partner." Interaction partners are entities that can provide couplings to an interaction. All systems are interaction partners, but not all interaction partners need to be systems. Interaction partners are implemented in the interaction_partner_t class and, because all systems are interaction partners, the system_t class is an extension of this class.

Often, the couplings a system requires from an interaction partner need to be combined with information from the system itself in some way before it is used. For example, to calculate the gravitational force acting on a planet due to the Sun, one needs the positions and masses of both the planet and the Sun. Because of this, besides handling the retrieval of the couplings from the partner, the interaction class also provides a interaction_oct_m::interaction_update deferred method that can be used to combine the couplings with information from the system.

When updating an interaction, the system will request this to be done for a specific iteration. The interaction then needs to get the couplings of the partner for that requested iteration. Because system and partner might increment their iterations at a different pace, the couplings might not always be available for the requested iteration. Different schemes are implemented to handle these cases. These are called timing methods. There are currently two of these methods implemented in the framwork. The first one is the "exact" timing. In that case the couplings must be at the requested iteration or the algorithm will refuse to proceed. The other one is the "retarded" timing, where the previous partner iteration closest to the requested iteration is used. Because the couplings used by the interaction might be out-of-sync with the partner information, the interaction needs to store a copy of them.

The process of updating an interaction is then a four step process:

1. Request the partner to update the couplings (see system_oct_m::system_update_couplings).
2. Check if the couplings are at the requested iteration or at a suitable iteration, depending on the timing method. If not, repeat step 1 until they are.
3. If necessary, request the partner to copy the couplings to the interaction.
4. Combine the couplings with the information from the system to upate the interaction.

Note that, from the point of view of this framework, it is perfectly possible to have a system interacting with itself. Because these "self-interactions" often need to be treated in a special way, a flag is provided in the interaction_t class to signal those cases.

Interactions can only be created after all systems are created. This is done by the call to the interactions_factory_t::create_interactions() function in run.F90:

    ! Create and initialize interactions
    !
    ! This function is called recursively for all subsystems of systems.
    ! If systems is a multisystem_basic_t container, the partners list contains all subsystems.
    call systems%create_interactions(interactions_factory, partners)

Data Types
interface	interaction_calculate
	All interactions need to implement the following deferred method, which takes information form the interaction partner and system to calculate the interaction. More...
interface	interaction_calculate_energy
	All interactions need to implement the following deferred method, which takes information form the interaction partner and system to calculate the interaction energy. More...
type	interaction_iterator_t
	These class extend the list and list iterator to make an interaction list. More...
type	interaction_list_t
	These classes extend the list and list iterator to make an interaction list. More...
type	interaction_t
	abstract interaction class More...

Functions/Subroutines
subroutine	interaction_update_partner_couplings (this, requested_iteration)
	Try to update all the couplings needed from the partner to update the interaction. More...
subroutine	interaction_update (this, requested_iteration)
	Update the interaction to the requested_iteration. More...
subroutine, public	interaction_end (this)
logical function	interaction_restart_read (this, namespace)
	read restart information More...
subroutine	interaction_restart_write (this, namespace)
subroutine	interaction_list_add_node (this, interaction)
class(interaction_t) function, pointer	interaction_iterator_get_next (this)

Variables
integer, parameter, public	timing_exact = 1
integer, parameter, public	timing_retarded = 2

Function/Subroutine Documentation

interaction_update_partner_couplings()

subroutine interaction_oct_m::interaction_update_partner_couplings ( class(interaction_t), intent(inout)  this, class(iteration_counter_t), intent(in)  requested_iteration  )

private

Try to update all the couplings needed from the partner to update the interaction.

Definition at line 287 of file interaction.F90.

interaction_update()

subroutine interaction_oct_m::interaction_update ( class(interaction_t), intent(inout)  this, class(iteration_counter_t), intent(in)  requested_iteration  )

private

Update the interaction to the requested_iteration.

Definition at line 352 of file interaction.F90.

interaction_end()

subroutine, public interaction_oct_m::interaction_end

(

class(interaction_t), intent(inout)

this

)

Definition at line 388 of file interaction.F90.

interaction_restart_read()

logical function interaction_oct_m::interaction_restart_read ( class(interaction_t), intent(inout)  this, type(namespace_t), intent(in)  namespace  )

private

read restart information

return .true. on success.

Definition at line 413 of file interaction.F90.

interaction_restart_write()

subroutine interaction_oct_m::interaction_restart_write ( class(interaction_t), intent(inout)  this, type(namespace_t), intent(in)  namespace  )

private

Definition at line 426 of file interaction.F90.

interaction_list_add_node()

subroutine interaction_oct_m::interaction_list_add_node ( class(interaction_list_t)  this, class(interaction_t), target  interaction  )

private

Definition at line 438 of file interaction.F90.

interaction_iterator_get_next()

class(interaction_t) function, pointer interaction_oct_m::interaction_iterator_get_next ( class(interaction_iterator_t), intent(inout)  this )

private

Definition at line 450 of file interaction.F90.

Variable Documentation

timing_exact

integer, parameter, public interaction_oct_m::timing_exact = 1

Definition at line 210 of file interaction.F90.

timing_retarded

integer, parameter, public interaction_oct_m::timing_retarded = 2

Definition at line 210 of file interaction.F90.