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