AstroBEAR Objects

Object Types

AstroBEAR uses objects to encapsulate data about certain features of the problem. At the user level, these objects simplify setups by making it easier to manage and manipulate certain physical features. At the developer level, they create consistency by providing a template for new physics.

Objects can be classified as one of four types:

• Initial Condition / Instantaneous sources: These objects create geometric features during problem setups. Unless they are somehow maintained, these objects can be altered or even dispersed by the dynamics of the simulation.
  • Ambient Object — simple object that can be used to set the default ambient background values.
  • Uniform Regions—regions where the hydrodynamic variables are homogenous (no gradients, no variations).
  • Split Regions
  • Clumps
  • Outflows
  • Colliding Flows

• Boundary Conditions: Objects that enforce special conditions on the boundaries of a domain.
  • Winds—Velocity conditions at one or more boundaries.

• Source Objects: These objects are used to model source terms. Source objects can be associated with a particular region (or even another object) or they can be applied to the entire problem domain.
  • Point Gravity Sources—These objects generate a central gravitational force around a specific point. These point sources are fixed unless attached to a sink particle.
  • Cooling Objects—These objects describe the radiative cooling mechanism associated with a specified region or domain. This cooling can be represented by an analytic function or (more commonly) a lookup table.

• Sink Particles—An additional object type that combines instantaneous and source term attributes, SinkParticles are moving particles that exert a central gravitational pull on the matter around them. Sink particles can be instantiated during the initial setup, or they can be generated during run time when sink particles are enabled and the Jeans instability criterion is met.

Sub-Objects

Many of these objects use geometric sub-objects that handle object shape and orientation. These objects are usually referenced by a pointer in the parent object, which means that multiple objects can reference the same sub-object.

• Shapes - Contains routines for orienting various physical objects
• Interfaces - Useful for dividing a region into two pieces based on a perturbed interface
• Perturbations - Useful for specifying a volume filling perturbation as a series expansion.
• Profiles - Useful for specifying a custom density, pressure or other type of profiles for an object.

Using Objects

All AstroBEAR objects share a common creation and destruction interface. To create a new object of type AstroObj, call the CreateAstroObj() subroutine in ProblemInitializeModule(). This creates a new object whose properties you can then modify. Many objects require further initialization to affect the problem domain, either before or during the run. These objects usually come with GridInit() and beforeStep() routines.

To make memory management less hellish, our objects also come with destruction routines. BE SURE TO USE THESE ROUTINES IF YOU PLAN ON DELETING AN OBJECT. This is the best way to make sure that all of the memory these objects use is safely freed.

Most of the AstroBEAR standard objects have the bulk of their inner workings encapsulated by simple subroutines. Review the documentation for each object carefully so that you understand how to use these routines; they are there to make object use simple and intuitive.

Object Development

Adding New Objects

The object system in AstroBEAR is intended to be flexible. There are, however, a few object management routines common to most objects. These routines amount to a standardized interface, and are recommended for any object that might one day be part of the regular build.

To create your new object of type Object, create a new module file in modules/objects. Then implement the following functions:

• InitObjects(): Sets up a global list of pointers to objects of type Object. This routine gets called in modules/module_control.f90::ModuleInit(). The list pointer itself is usually part of the object module.
• CreateObject(ObjPointer[, args]): Creates a new Object-type object, allocating whatever variables are needed. This is usually called in a problem's ProblemModuleInit() routine.
• InitializeObject(ObjPointer[, args]): Sets the data attributes of the new object. This also gets called in a problem's ProblemModuleInit() routine, shortly after the object's creation.
• AddObjectToList(ObjPointer): Adds the object ObjPointer to the global list of Object-type objects. While it is consider part of the standard object interface, this routine is more often than not called from within InitializeObject().
• RemoveObjectFromList(ObjPointer): Adds the object ObjPointer to the global list of Object-type objects. This routine is usually part of the object destruction process, so it is often called in the DestroyObject() routine.
• DestroyObject(ObjPointer[, args]): Deletes an object, freeing up the object's allocated memory. This can be used almost anywhere, but is most often used in control modules.

Objects which have a physical representation in the problem data have some additional standard routines:

• ObjectGridInit(Info): It takes a grid structure Info, finds all the objects of type Object that exist at least partially inside it, and creates their representations within Info's data. This routine gets called in modules/module_control.f90::GridInit().
• ObjectBeforeStep(Info): This routine is only needed objects which have a regularly renewed effect. It takes a grid structure Info, finds all the objects of type Object that exist at least partially inside it, and applies their timestep condition to Info's data. This routine gets called in modules/module_control.f90::BeforeStep().

These are just the routines required so that AstroBEAR can consistently interact with your object; you will no doubt have others.

Modifying Existing Objects

Adding features to existing objects is fairly straightforward—simply add the required attributes to the object's definition and include whatever additional methods operate on that object. It is important to remember, though, that other people rely on these objects to behave as advertised. To be on the safe side, make sure that your new feature is turned off by default. That way, you aren't leaving nasty surprises for other people who use the object.

Modifications are a little trickier, especially if you are substantially changing the behavior of the object. Developers are advised to consult with the AstroBEAR team before modifying the behavior of existing objects, so that the changes can be thoroughly vetted and announced to the community at large.

IMPORTANT: Everything above goes double for adding to or modifying the sub-objects. Virtually all of AstroBEAR's standard objects rely on at least one sub-object to function correctly; if you want to tamper with a sub-object:

a) Be careful.

b) Consult with the AstroBEAR team early and often.

c) Repeat a and b.

Information on Existing objects

• Uniform Regions
• Split Regions
• Clumps
• Winds
• Point Gravity Sources
• Outflow Sources

Information on SubObjects

• Shapes
• Interfaces