The SKIRT project
advanced radiative transfer for astrophysics
Public Member Functions | Protected Member Functions | Private Types | Private Attributes | Friends | List of all members
DynamicStateRecipe Class Referenceabstract

#include <DynamicStateRecipe.hpp>

Inheritance diagram for DynamicStateRecipe:
Inheritance graph
[legend]

Public Member Functions

virtual void beginUpdate (int numCells)=0
 
virtual bool endUpdate (int numCells, int numUpdated, int numNotConverged)
 
int maxNotConvergedCells () const
 
virtual UpdateStatus update (MaterialState *state, const Array &Jv)=0
 
- Public Member Functions inherited from SimulationItem
template<class T >
T * find (bool setup=true) const
 
template<class T >
T * interface (int levels=-999999, bool setup=true) const
 
virtual string itemName () const
 
void setup ()
 
string typeAndName () const
 
- Public Member Functions inherited from Item
 Item (const Item &)=delete
 
virtual ~Item ()
 
void addChild (Item *child)
 
const vector< Item * > & children () const
 
virtual void clearItemListProperty (const PropertyDef *property)
 
void destroyChild (Item *child)
 
virtual bool getBoolProperty (const PropertyDef *property) const
 
virtual vector< double > getDoubleListProperty (const PropertyDef *property) const
 
virtual double getDoubleProperty (const PropertyDef *property) const
 
virtual string getEnumProperty (const PropertyDef *property) const
 
virtual int getIntProperty (const PropertyDef *property) const
 
virtual vector< Item * > getItemListProperty (const PropertyDef *property) const
 
virtual Item * getItemProperty (const PropertyDef *property) const
 
virtual string getStringProperty (const PropertyDef *property) const
 
int getUtilityProperty (string name) const
 
virtual void insertIntoItemListProperty (const PropertyDef *property, int index, Item *item)
 
Item & operator= (const Item &)=delete
 
Item * parent () const
 
virtual void removeFromItemListProperty (const PropertyDef *property, int index)
 
virtual void setBoolProperty (const PropertyDef *property, bool value)
 
virtual void setDoubleListProperty (const PropertyDef *property, vector< double > value)
 
virtual void setDoubleProperty (const PropertyDef *property, double value)
 
virtual void setEnumProperty (const PropertyDef *property, string value)
 
virtual void setIntProperty (const PropertyDef *property, int value)
 
virtual void setItemProperty (const PropertyDef *property, Item *item)
 
virtual void setStringProperty (const PropertyDef *property, string value)
 
void setUtilityProperty (string name, int value)
 
virtual string type () const
 

Protected Member Functions

 DynamicStateRecipe ()
 
- Protected Member Functions inherited from SimulationItem
 SimulationItem ()
 
virtual bool offersInterface (const std::type_info &interfaceTypeInfo) const
 
virtual void setupSelfAfter ()
 
virtual void setupSelfBefore ()
 
- Protected Member Functions inherited from Item
 Item ()
 

Private Types

using BaseType = SimulationItem
 
using ItemType = DynamicStateRecipe
 

Private Attributes

int _maxNotConvergedCells
 

Friends

class ItemRegistry
 

Detailed Description

DynamicStateRecipe is an abstract class representing recipes for dynamically adjusting the medium state while iterating over the radiation field during primary and/or secondary emission. The purpose of the dynamic medium state (DMS) mechanism is to allow self-consistent calculation of medium state variables. For more information about DMS support, refer to the documentation of the MonteCarloSimulation class. In the current implementation, the updates performed by DynamicStateRecipe subclasses are assumed to affect the opacity of the medium during primary emission. In other words, DynamicStateRecipe's always implement PDMS. A prototypical example of a PDMS application is the radiative destruction of dust grains.

For each iteration step, the simulation launches a set of photon packets to track the radiation field based on the current values of the medium state variables. At the end of the iteration step, the dynamic medium state recipes configured for the simulation are given a chance to update the medium state variables based on the established radiation field. The iteration continues until all recipes indicate convergence (or the configured maximum number of iterations has been reached).

At the end of each iteration step, the functions for each configured recipe are called in the following order: the beginUpdate() function; the update() function for each spatial cell and for each medium component in the simulation; and finally the endUpdate() function. The latter function returns a Boolean that indicates whether the iteration can be considered to have converged for this recipe.

A recipe is allowed to discover information about the configuration of the simulation, for example to determine the type of material mixes associated with the various medium components. However, it should not update any information outside its own data members except through the material states passed to the update() function. Furthermore, the operation of the update() function should solely depend on and affect changes to the material state passed to that particular invocation of the function. In other words, each spatial cell/component must be treated independently from other spatial cells/components.

The functions for multiple recipes are invoked in the user-configured order for each particular cell (but may be otherwise interleaved in any order). Assuming two recipes A and B, configured in this order, recipe B will thus always see the state as it has been adjusted by recipe A.

These requirements and guarantees allow the update() function to be called for different spatial cell/component combinations in parallel execution threads and in multiple parallel processes, and thus in arbitrary order. A possible execution sequence could be:

for r in recipes:
    r.beginUpdate()

parallel for m in spatial cells:
    for r in recipes:
        for h in medium components:
            r.update(m, h)

for r in recipes:
    r.endUpdate()

Constructor & Destructor Documentation

◆ DynamicStateRecipe()

DynamicStateRecipe::DynamicStateRecipe ( )
inlineprotected

Default constructor for abstract Item subclass DynamicStateRecipe : "a dynamic medium state recipe" .

Member Function Documentation

◆ beginUpdate()

virtual void DynamicStateRecipe::beginUpdate ( int  numCells)
pure virtual

This function is called before updating begins at the end of each iteration step. The numCells argument specifies the number of spatial cells in the simulation. The implementation in a subclass can perform the following tasks, if applicable:

  • gather and cache information about the simulation at large (this is easier done here than during setup because recipe instances are being setup before the medium system of which they are a part).
  • initialize the data members that track convergence data for the recipe in case the recipe requires more information than the number of updated spatial cells, which is automatically provided to the endUpdate() function.

Implemented in ClearDensityRecipe, and DustDestructionRecipe.

◆ endUpdate()

virtual bool DynamicStateRecipe::endUpdate ( int  numCells,
int  numUpdated,
int  numNotConverged 
)
virtual

This function is called after updating has completed at the end of each iteration step. It returns true if, based on the given spatial cell statistics, the recipe has converged. Otherwise it returns false. The numCells, numUpdated and numNotConverged arguments specify respectively the number of spatial cells in the simulation, the number of cells updated during this update cycle, and the number of updated cells that have not yet converged.

The default implementation in this base class returns true if the actual number of not-converged cells does not exceed the configured maximum number of not-converged cells, and false otherwise. Subclasses may provide more complex implementations. In case a recipe needs to tracks additional information in the update() function, the tracked data must be aggregated across processes because the update() function can be called from separate parallel processes.

◆ maxNotConvergedCells()

DynamicStateRecipe::maxNotConvergedCells ( ) const
inline

This function returns the value of the discoverable integer property maxNotConvergedCells : "the number of spatial cells allowed to not converge" .

The minimum value for this property is "0" .

The default value for this property is given by the conditional value expression "0" .

◆ update()

virtual UpdateStatus DynamicStateRecipe::update ( MaterialState *  state,
const Array &  Jv 
)
pure virtual

This function is called during updating at the end of each iteration step. If needed, it updates the specified material state (corresponding to a particular spatial cell and medium component) based on the specified radiation field (corresponding to that same cell and discretized on the simulation's radiation field wavelength grid as returned by the Configuration::radiationFieldWLG() function). The function returns the update status as described for the UpdateStatus class.

If applicable, the implementation in a subclass should also update the data members that track additional convergence data for the recipe. Because the update() function can be called from multiple parallel execution threads, those updates must be performed atomically or be properly protected by a lock.

Implemented in ClearDensityRecipe, and DustDestructionRecipe.

The documentation for this class was generated from the following file:
The SKIRT project -- advanced radiative transfer for astrophysics © Astronomical Observatory, Ghent University