Stellar Dynamics Interface Definition¶
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 opportunity 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
 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

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
 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

Object State, Extension Mechanism¶
Not all information of a particle can be transferred 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
 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

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
 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

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
 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

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
 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

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
 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

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
 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

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
 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

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