Stellar Dynamics Interface Definition

Date Author(s) Version State
13-10-2009 AvE 0.1 Initial
20-10-2009 AvE 0.2 Initial, after first review with IP
02-11-2009 AvE 0.3 Initial, after second review with MR

Introduction

In this chapter we describe the common interface for all stellar dynamics codes.

Parameters

Gravity dynamics codes have at least one specified parameter. Other parameters need to be specified on a per code basis. All parameters have to be accessed with functions following the template of the get_eps and set_eps functions. A parameter access function may only retrieve or update the value of a single parameter. After all parameters have been set, the initialize_code function should be called, this gives the code the opertunity prepare the model.

class amuse.community.interface.gd.GravitationalDynamicsInterface
get_eps2

Retrieve the current value of the squared smoothing parameter.

int32 get_eps2(float64 * epsilon_squared);
FUNCTION get_eps2(epsilon_squared)
  DOUBLE PRECISION :: epsilon_squared
  INTEGER :: get_eps2
END FUNCTION
Parameters:epsilon_squared (float64, OUT) – The current value of the smooting parameter, squared.
Returns:
0 - OK
Current value of the smoothing parameter was set
-1 - ERROR
The code does not have support for a smoothing parameter
initialize_code

Run the initialization for the code, called before any other call on the code (so before any parameters are set or particles are defined in the code).

int32 initialize_code();
FUNCTION initialize_code()
  INTEGER :: initialize_code
END FUNCTION
Returns:
0 - OK
Code is initialized
-1 - ERROR
Error happened during initialization, this error needs to be further specified by every code implemention
-2 - ERROR
not yet implemented
set_eps2

Update the value of the squared smoothing parameter.

int32 set_eps2(float64 epsilon_squared);
FUNCTION set_eps2(epsilon_squared)
  DOUBLE PRECISION :: epsilon_squared
  INTEGER :: set_eps2
END FUNCTION
Parameters:epsilon_squared (float64, IN) – The new value of the smooting parameter, squared.
Returns:
0 - OK
Current value of the smoothing parameter was set
-1 - ERROR
The code does not have support for a smoothing parameter

Object Management

Most gravitational dynamics codes work on particles (stars, black holes or gas). The following methods define the functionality to create, remove and query the particles in the code. Currently the interface does not handle different types of particles

class amuse.community.interface.gd.GravitationalDynamicsInterface
delete_particle

Remove the definition of particle from the code. After calling this function the particle is no longer part of the model evolution. It is up to the code if the index will be reused. This function is optional.

int32 delete_particle(int32 index_of_the_particle);
FUNCTION delete_particle(index_of_the_particle)
  INTEGER :: index_of_the_particle
  INTEGER :: delete_particle
END FUNCTION
Parameters:index_of_the_particle (int32, IN) – Index of the particle to be removed. This index must have been returned by an earlier call to new_particle()
Returns:
0 - OK
particle was removed from the model
-1 - ERROR
particle could not be removed
-2 - ERROR
not yet implemented
get_index_of_first_particle

Retrieve the index of first particle. When this index is used as the starting index for the get_index_of_next_particle method, all particles can be iterated over:

error, first_index = instance.get_index_of_first_particle()
current_index = first_index
while error == 0:
    status, mass = instance.get_mass(current_index)
    print mass
    error, current_index = instance.get_index_of_next_particle(current_index)
int32 get_index_of_first_particle(int32 * index_of_the_particle);
FUNCTION get_index_of_first_particle(index_of_the_particle)
  INTEGER :: index_of_the_particle
  INTEGER :: get_index_of_first_particle
END FUNCTION
Parameters:index_of_the_particle (int32, OUT) – Index of the first particle
Returns:
0 - OK
Index was set
1 - ERROR
Code has no particles, or cannot set the index
get_index_of_next_particle

Retrieve the index of the particle following the provided index. The iteration direction is determined by the code.

int32 get_index_of_next_particle(int32 index_of_the_particle, 
  int32 * index_of_the_next_particle);
FUNCTION get_index_of_next_particle(index_of_the_particle,  &
    index_of_the_next_particle)
  INTEGER :: index_of_the_particle, index_of_the_next_particle
  INTEGER :: get_index_of_next_particle
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle
  • index_of_the_next_particle (int32, OUT) – Index of the particle following the particle with the provided index
Returns:

0 - OK

Index was set

1 - STATE

Last index was reached

-1 - ERROR

Particle could not be found

get_number_of_particles

Retrieve the total number of particles define d in the code

int32 get_number_of_particles(int32 * number_of_particles);
FUNCTION get_number_of_particles(number_of_particles)
  INTEGER :: number_of_particles
  INTEGER :: get_number_of_particles
END FUNCTION
Parameters:number_of_particles (int32, OUT) – Count of the particles in the code
Returns:
0 - OK
Count could be determined
-1 - ERROR
Unable to determine the count
new_particle

Define a new particle in the stellar dynamics code. The particle is initialized with the provided mass, radius, position and velocity. This function returns an index that can be used to refer to this particle.

int32 new_particle(int32 * index_of_the_particle, float64 mass, 
  float64 x, float64 y, float64 z, float64 vx, float64 vy, float64 vz, 
  float64 radius);
FUNCTION new_particle(index_of_the_particle, mass, x, y, z, vx, vy, vz,  &
    radius)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: mass, x, y, z, vx, vy, vz, radius
  INTEGER :: new_particle
END FUNCTION
Parameters:
  • index_of_the_particle (int32, OUT) – An index assigned to the newly created particle. This index is supposed to be a local index for the code (and not valid in other instances of the code or in other codes)
  • mass (float64, IN) – The mass of the particle
  • x (float64, IN) – The initial position vector of the particle
  • y (float64, IN) – The initial position vector of the particle
  • z (float64, IN) – The initial position vector of the particle
  • vx (float64, IN) – The initial velocity vector of the particle
  • vy (float64, IN) – The initial velocity vector of the particle
  • vz (float64, IN) – The initial velocity vector of the particle
  • radius (float64, IN) – The radius of the particle
Returns:

0 - OK

particle was created and added to the model

-1 - ERROR

particle could not be created

Object state

Particles in gravitational dynamics have a well known, minimal state. This state is is defined by a location, velocity and mass and radius. The state can be retrieved and updated with the following functions.

class amuse.community.interface.gd.GravitationalDynamicsInterface
get_state

Retrieve the current state of a particle. The minimal information of a stellar dynamics particle (mass, radius, position and velocity) is returned.

int32 get_state(int32 index_of_the_particle, float64 * mass, float64 * x, 
  float64 * y, float64 * z, float64 * vx, float64 * vy, float64 * vz, 
  float64 * radius);
FUNCTION get_state(index_of_the_particle, mass, x, y, z, vx, vy, vz,  &
    radius)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: mass, x, y, z, vx, vy, vz, radius
  INTEGER :: get_state
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle to get the state from. This index must have been returned by an earlier call to new_particle()
  • mass (float64, OUT) – The current mass of the particle
  • x (float64, OUT) – The current position vector of the particle
  • y (float64, OUT) – The current position vector of the particle
  • z (float64, OUT) – The current position vector of the particle
  • vx (float64, OUT) – The current velocity vector of the particle
  • vy (float64, OUT) – The current velocity vector of the particle
  • vz (float64, OUT) – The current velocity vector of the particle
  • radius (float64, OUT) – The current radius of the particle
Returns:

0 - OK

particle was removed from the model

-1 - ERROR

particle could not be found

set_state

Update the current state of a particle. The minimal information of a stellar dynamics particle (mass, radius, position and velocity) is updated.

int32 set_state(int32 index_of_the_particle, float64 mass, float64 x, 
  float64 y, float64 z, float64 vx, float64 vy, float64 vz, 
  float64 radius);
FUNCTION set_state(index_of_the_particle, mass, x, y, z, vx, vy, vz,  &
    radius)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: mass, x, y, z, vx, vy, vz, radius
  INTEGER :: set_state
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle for which the state is to be updated. This index must have been returned by an earlier call to new_particle()
  • mass (float64, IN) – The new mass of the particle
  • x (float64, IN) – The new position vector of the particle
  • y (float64, IN) – The new position vector of the particle
  • z (float64, IN) – The new position vector of the particle
  • vx (float64, IN) – The new velocity vector of the particle
  • vy (float64, IN) – The new velocity vector of the particle
  • vz (float64, IN) – The new velocity vector of the particle
  • radius (float64, IN) – The new radius of the particle
Returns:

0 - OK

particle was found in the model and the information was set

-1 - ERROR

particle could not be found

-2 - ERROR

code does not support updating of a particle

-3 - ERROR

not yet implemented

Object State, Extension Mechanism

Not all information of a particle can be transfered with the get_state and set_state functions. To support other properties (like acceleration), the code can define get_ and set_ functions. These functions must get or set one scalar property (1 argument) or a vector property (3 arguments)

class amuse.community.interface.gd.GravitationalDynamicsInterface
get_acceleration

Retrieve the acceleration vector of a particle. Second time derivative of the position.

int32 get_acceleration(int32 index_of_the_particle, float64 * ax, 
  float64 * ay, float64 * az);
FUNCTION get_acceleration(index_of_the_particle, ax, ay, az)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: ax, ay, az
  INTEGER :: get_acceleration
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle to get the state from. This index must have been returned by an earlier call to new_particle()
  • ax (float64, OUT) – The current position vector of the particle
  • ay (float64, OUT) – The current position vector of the particle
  • az (float64, OUT) – The current position vector of the particle
Returns:

0 - OK

current value was retrieved

-1 - ERROR

particle could not be found

-2 - ERROR

not yet implemented

get_mass

Retrieve the mass of a particle. Mass is a scalar property of a particle, this function has one OUT argument.

int32 get_mass(int32 index_of_the_particle, float64 * mass);
FUNCTION get_mass(index_of_the_particle, mass)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: mass
  INTEGER :: get_mass
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle to get the state from. This index must have been returned by an earlier call to new_particle()
  • mass (float64, OUT) – The current mass of the particle
Returns:

0 - OK

particle was removed from the model

-1 - ERROR

particle could not be found

get_position

Retrieve the position vector of a particle. Position is a vector property, this function has 3 OUT arguments.

int32 get_position(int32 index_of_the_particle, float64 * x, float64 * y, 
  float64 * z);
FUNCTION get_position(index_of_the_particle, x, y, z)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: x, y, z
  INTEGER :: get_position
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle to get the state from. This index must have been returned by an earlier call to new_particle()
  • x (float64, OUT) – The current position vector of the particle
  • y (float64, OUT) – The current position vector of the particle
  • z (float64, OUT) – The current position vector of the particle
Returns:

0 - OK

current value was retrieved

-1 - ERROR

particle could not be found

-2 - ERROR

not yet implemented

get_potential

Retrieve the potential at a particle position, for retrieving the potential anywhere in the field use get_potential_at_point.

int32 get_potential(int32 index_of_the_particle, float64 * potential);
FUNCTION get_potential(index_of_the_particle, potential)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: potential
  INTEGER :: get_potential
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle for which the state is to be updated. This index must have been returned by an earlier call to new_particle()
  • potential (float64, OUT) – The current scalar potential...
Returns:

0 - OK

current value was retrieved

-1 - ERROR

particle could not be found

-2 - ERROR

not yet implemented

set_acceleration

Update the acceleration of a particle. Defined for symetry with the get_acceleration function. Should be removed if physaccily unsound Maybe moved to snapshot support functionality

int32 set_acceleration(int32 index_of_the_particle, float64 ax, 
  float64 ay, float64 az);
FUNCTION set_acceleration(index_of_the_particle, ax, ay, az)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: ax, ay, az
  INTEGER :: set_acceleration
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle for which the state is to be updated. This index must have been returned by an earlier call to new_particle()
  • ax (float64, IN) – The new acceleration vector of the particle
  • ay (float64, IN) – The new acceleration vector of the particle
  • az (float64, IN) – The new acceleration vector of the particle
Returns:

0 - OK

particle was found in the model and the information was set

-1 - ERROR

particle could not be found

-2 - ERROR

code does not support updating of a particle

-3 - ERROR

not yet implemented

set_mass

Update the mass of a particle. Mass is a scalar property of a particle.

int32 set_mass(int32 index_of_the_particle, float64 mass);
FUNCTION set_mass(index_of_the_particle, mass)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: mass
  INTEGER :: set_mass
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle for which the state is to be updated. This index must have been returned by an earlier call to new_particle()
  • mass (float64, IN) – The new mass of the particle
Returns:

0 - OK

particle was found in the model and the information was set

-1 - ERROR

particle could not be found

-2 - ERROR

code does not support updating of a particle

set_position

Update the position of a particle.

int32 set_position(int32 index_of_the_particle, float64 x, float64 y, 
  float64 z);
FUNCTION set_position(index_of_the_particle, x, y, z)
  INTEGER :: index_of_the_particle
  DOUBLE PRECISION :: x, y, z
  INTEGER :: set_position
END FUNCTION
Parameters:
  • index_of_the_particle (int32, IN) – Index of the particle for which the state is to be updated. This index must have been returned by an earlier call to new_particle()
  • x (float64, IN) – The new position vector of the particle
  • y (float64, IN) – The new position vector of the particle
  • z (float64, IN) – The new position vector of the particle
Returns:

0 - OK

particle was found in the model and the information was set

-1 - ERROR

particle could not be found

-2 - ERROR

code does not support updating of a particle

Model evolution

The gravitational dynamics codes evolve the properties of the particles in time. The following functions are needed to control the evolution in the code.

class amuse.community.interface.gd.GravitationalDynamicsInterface
commit_particles

Let the code perform initialization actions after all particles have been loaded in the model. Should be called before the first evolve call and after the last new_particle call.

int32 commit_particles();
FUNCTION commit_particles()
  INTEGER :: commit_particles
END FUNCTION
Returns:
0 - OK
Model is initialized and evolution can start
-1 - ERROR
Error happened during initialization, this error needs to be further specified by every code implemention

Diagnostics

The state of the code can be queried, before, during and after the model calculations. The following function can be used to query the exact model time, the total energies and colliding particles.

class amuse.community.interface.gd.GravitationalDynamicsInterface
get_center_of_mass_position

Retrieve the center of mass (a point in space) of all particles.

int32 get_center_of_mass_position(float64 * x, float64 * y, float64 * z);
FUNCTION get_center_of_mass_position(x, y, z)
  DOUBLE PRECISION :: x, y, z
  INTEGER :: get_center_of_mass_position
END FUNCTION
Parameters:
  • x (float64, OUT) – The center of mass of the model
  • y (float64, OUT) – The center of mass of the model
  • z (float64, OUT) – The center of mass of the model
Returns:

0 - OK

Current value of the center was retrieved

-1 - ERROR

The mass could not be provided

-2 - ERROR

not yet implemented

get_center_of_mass_velocity

Retrieve the velocity of the center of mass of all particles. This velocity is mass weighted mean of the velocity of all particles.

int32 get_center_of_mass_velocity(float64 * vx, float64 * vy, 
  float64 * vz);
FUNCTION get_center_of_mass_velocity(vx, vy, vz)
  DOUBLE PRECISION :: vx, vy, vz
  INTEGER :: get_center_of_mass_velocity
END FUNCTION
Parameters:
  • vx (float64, OUT) – The mean velocity of the model
  • vy (float64, OUT) – The mean velocity of the model
  • vz (float64, OUT) – The mean velocity of the model
Returns:

0 - OK

Current value of the center of mass velocity was retrieved

-1 - ERROR

The value could not be provided

get_kinetic_energy

Retrieve the current kinetic energy of the model

int32 get_kinetic_energy(float64 * kinetic_energy);
FUNCTION get_kinetic_energy(kinetic_energy)
  DOUBLE PRECISION :: kinetic_energy
  INTEGER :: get_kinetic_energy
END FUNCTION
Parameters:kinetic_energy (float64, OUT) – The kinetic energy of the model
Returns:
0 - OK
Current value of the kinetic energy was set
-1 - ERROR
Kinetic energy could not be provided
get_potential_energy

Retrieve the current potential energy of the model

int32 get_potential_energy(float64 * potential_energy);
FUNCTION get_potential_energy(potential_energy)
  DOUBLE PRECISION :: potential_energy
  INTEGER :: get_potential_energy
END FUNCTION
Parameters:potential_energy (float64, OUT) – The potential energy of the model
Returns:
0 - OK
Current value of the potential energy was set
-1 - ERROR
Kinetic potential could not be provided
get_time

Retrieve the model time. This time should be close to the end time specified in the evolve code. Or, when a collision was detected, it will be the model time of the collision.

int32 get_time(float64 * time);
FUNCTION get_time(time)
  DOUBLE PRECISION :: time
  INTEGER :: get_time
END FUNCTION
Parameters:time (float64, OUT) – The current model time
Returns:
0 - OK
Current value of the time was retrieved
-1 - ERROR
The code does not have support for querying the time
get_total_mass

Retrieve the sum of the masses of all particles.

int32 get_total_mass(float64 * mass);
FUNCTION get_total_mass(mass)
  DOUBLE PRECISION :: mass
  INTEGER :: get_total_mass
END FUNCTION
Parameters:mass (float64, OUT) – The total mass of the model
Returns:
0 - OK
Current value of the kinetic mass was retrieved
-1 - ERROR
Total mass could not be provided
-2 - ERROR
not yet implemented
get_total_radius

Return the radius of the sphere, centered on the center of mass that contains all the particles. get_size?

int32 get_total_radius(float64 * radius);
FUNCTION get_total_radius(radius)
  DOUBLE PRECISION :: radius
  INTEGER :: get_total_radius
END FUNCTION
Parameters:radius (float64, OUT) – The maximum distance from a star to the center of mass of the model
Returns:
0 - OK
Current value of the radius was retrieved
-1 - ERROR
The value could not be provided

Services

Some Gravitational Dynamics codes can provide services for other codes. Currently calculating the gravity at a given point is the only specified function.

class amuse.community.interface.gd.GravitationalDynamicsInterface