Date  Author(s)  Version  State 

13102009  AvE  0.1  Initial 
20102009  AvE  0.2  Initial, after first review with IP 
02112009  AvE  0.3  Initial, after second review with MR 
In this chapter we describe the common interface for all stellar dynamics codes.
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.
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: 

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: 


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: 

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

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: 

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: 


Returns: 

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: 

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: 


Returns: 

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


Returns: 

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: 


Returns: 

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


Returns: 

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: 


Returns: 

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: 


Returns: 

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: 


Returns: 

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: 


Returns: 

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: 


Returns: 

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: 


Returns: 

The gravitational dynamics codes evolve the properties of the particles in time. The following functions are needed to control the evolution in the code.
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: 


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


Returns: 

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: 


Returns: 

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: 

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: 

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: 

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: 

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: 

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