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 opportunity 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
epsilon_squared (float64, OUT) – The current value of the smooting parameter, squared.
Current value of the smoothing parameter was set
The code does not have support for a smoothing parameter
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
Code is initialized
Error happened during initialization, this error needs to be further specified by every code implementation
not yet implemented
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
epsilon_squared (float64, IN) – The new value of the smooting parameter, squared.
Current value of the smoothing parameter was set
The code does not have support for a smoothing parameter
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
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()
particle was removed from the model
particle could not be removed
not yet implemented
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
index_of_the_particle (int32, OUT) – Index of the first particle
Index was set
Code has no particles, or cannot set the index
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
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
Index was set
Last index was reached
Particle could not be found
Retrieve the total number of particles defined 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
number_of_particles (int32, OUT) – Count of the particles in the code
Count could be determined
Unable to determine the count
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
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
particle was created and added to the model
particle could not be created
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
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
particle was removed from the model
particle could not be found
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
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
particle was found in the model and the information was set
particle could not be found
code does not support updating of a particle
not yet implemented
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)
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
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 acceleration vector of the particle
ay (float64, OUT) – The current acceleration vector of the particle
az (float64, OUT) – The current acceleration vector of the particle
current value was retrieved
particle could not be found
not yet implemented
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
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
particle was removed from the model
particle could not be found
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
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
current value was retrieved
particle could not be found
not yet implemented
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
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…
current value was retrieved
particle could not be found
not yet implemented
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
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
particle was found in the model and the information was set
particle could not be found
code does not support updating of a particle
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
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
particle was found in the model and the information was set
particle could not be found
code does not support updating of a particle
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
Model is initialized and evolution can start
Error happened during initialization, this error needs to be further specified by every code implemention
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
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
Current value of the center was retrieved
The mass could not be provided
not yet implemented
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
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
Current value of the center of mass velocity was retrieved
The value could not be provided
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
kinetic_energy (float64, OUT) – The kinetic energy of the model
Current value of the kinetic energy was set
Kinetic energy could not be provided
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
potential_energy (float64, OUT) – The potential energy of the model
Current value of the potential energy was set
Kinetic potential could not be provided
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
time (float64, OUT) – The current model time
Current value of the time was retrieved
The code does not have support for querying the time
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
mass (float64, OUT) – The total mass of the model
Current value of the kinetic mass was retrieved
Total mass could not be provided
not yet implemented
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
radius (float64, OUT) – The maximum distance from a star to the center of mass of the model
Current value of the radius was retrieved
The value could not be provided
Some Gravitational Dynamics codes can provide services for other codes. Currently calculating the gravity at a given point is the only specified function.