COSMIX 0.4 Beta

Getting Started Manual

I./ Introduction

Je suis désolé... Une version française de COSMIX sera bientôt disponible. C'est simplement qu'ayant pris l'habitude de programmer en anglais, il était plus facile de le documenter en anglais...

As will become apparent in the course of this document, this is only a pre-release of COSMIX. What this means is that there are a number of features which have only been partially implemented yet. I have tried to disable them so the interface remains fully functional but I realize some user actions may still remain without effect. I am sorry about that. I still hope you enjoy using COSMIX to experience a little of the might and the complexity which are behind the creation of solar systems or, more generally, of n body systems.

This document aims at helping users in their first contact with COSMIX 0.4 Beta. It will present:

It is NOT a complete documentation for COSMIX, nor part of the celestial mechanics' tutorial. These are still under construction and will appear as part of the future releases of COSMIX. The interface, which I am about to describe, will then be closely connected to tutorial references and online help, and COSMIX will then not only be a simulator but also an interactive classroom for learning celestial mechanics.

 

II./ Sample session

This is only a sample session, please refer to the rest of this help document if anything is unclear or for additional details.

III./ The Interface

COSMIX is designed as a control center, a celestial control center which allows the user to build his own physical systems then observe them, finally interpret them physically speaking. As such, it is built around 3 main different modules, one for the creation of the system (the definition "page": Def.), two for the observation and the analysis of the resulting dynamics (the graphical "page" for graphical display: Grp. and a "page" for numerical data: Tbl.). There is an additional module to automate the creation of complex systems via scripting (the scripting "page": Scr.).

1./ The Def. Page

The Def. page serves for defining the system and allows the user to see how his masses are distributed in space and to see their initial speed vectors. It contains essentially 4 orthogonal viewpoints displaying the initial conditions which define the system. The dimensions of these viewpoints are set adaptively so that the entire system can be seen. The punctual masses are represented by 3*3 pixels square whose color depend on whether the body is "active" for the simulation (see below for an explanation of what this means), green means yes, red means no. Their speed vectors are displayed as dotted lines and are represented with the same scale as the system. The 4 viewpoints are freely resizable using the handle bars which are visible between them. They default to the following orientations (no navigation has yet been implemented):

The example below displays the following system:

 

2./ The Control Panel

As you have probably noticed the Def. page in the main window does not permit any entries (it will, in the future versions, be used for defining bodies using the mouse). The control panel is used for this purpose. It allows the user to define the system regardless of the active page, so he can set it up by looking at the mass distribution in Def. page or by looking at the numerical data in the Tbl. page or... who knows what...

It describes the system as a tree. Each body is a node in this tree and has a number of dependencies:

After creation of a new object, the red crosses in the "Ok" column indicate that as the physical and kinetic properties have not yet been defined the object is not ready for being part of the simulation. Defining these appropriately changes these crosses into green ticks saying they are operational. The icon in the "Status" column indicates whether the object will be part of the simulated system. Selecting an object and clicking on the "Status" button allows the user the easily study the effects of any object on the behavior of the system. Similarly a name may be associated to an object (by clicking on the "Name" button) and comments to it and each of its active dependencies.

A middle click brings up a menu specific to managing the system tree. Its functions are pretty self-evident.

A left click brings up the entries corresponding to the selected node. For physical parameters the entries concern mass and dimension, for kinetics they are relative to position and speed:

 

 

Navigation through the different entry can be done using the mouse, the Tab key or the arrow keys. The entries only accept numerical values and must be validated by pressing the "Enter" key at which point they are displayed with the scientific convention and a 7-digits mantissa and an exponent (the internal representation uses "double"-type variables so the parameters may be stored with more precision than what is displayed). Some entries have additional requirements: mass must be a positive number, etc...

The user sets up the simulation parameters using the entries which are locate at the bottom of the control panel. They include the time interval (with the restriction that start be anterior to stop, but this will be removed in future versions), the time step of computed states and constraints on the precision of the calculation. The integrator is a high order Runge-Kutta method with adaptive time steps which outputs a continuous solution. Hence this continuous solution is sampled according to the constant time step defined by the user, but this operation does not affect the precision of the computation nor the precision of the numerical data in the Tbl. page. It only affects the complexity of the curves in the Grp. page.

As can be seen from the previous screenshots not all fields are required to make a system valid (the dimension field is currently not required as the integrator does not check for collisions, i.e. this field is not yet functional) or a simulation valid (the relative and absolute accuracy have default values which are used if none are given).

3./ The Grp. Page

The Grp page contains essentially the same elements as the Def. page, except they are used for different purposes. The four viewpoints serve to display the computed trajectories of the n bodies under the Newtonian law of gravitation. The computed positions are represented in red and are interpolated using yellow NURBS curves. These viewpoints present a perspective view of the system (as opposed to the orthogonal viewpoints of the Def. page) and default to the same orientations as those in the Def. page and to displaying all the trajectories. Navigation tools have been implemented for these:

Once the trajectories have been computed, it looks like this:

 

4./ The Tbl. Page

The Tbl page displays the numerical results which have been computed. The properties of each object are displayed first, then the parameters concerning the system as a whole. Entries are listed according to the moment in time to which they correspond. Numerical tools will be associated to this page, but for now it mainly serves the purpose of displaying the simulated data in a scientifically usable form (measuring energy, force, momentum... and it can be exported as a text file). The data is displayed with the scientific convention and with up to 6 significant digits.

 

5./ The Scr. Page

This is the script page. It displays the script corresponding to the current system (after it has been saved, i.e. after the script has been written). Such scripts are xml files (which is an extension of hmtl which allows the designer to define his own tags). It follows a set of rules which are defined in the xml specifications and in the system.dtd file. This file should be used by COSMIX to determine whether a script is valid or not, but that is not currently working. What this means is that you may very well construct systems by writing such scripts, but COSMIX does not yet have an internal "debugger" for those scripts and hence loading them as systems may provoke segmentation fault errors. Systems and scripts are actually the same files in the sense that saving a systems causes COSMIX to write down the corresponding script and loading a system causes COSMIX to parse one such script.

The following example shows the Scr. page and a simple system composed if 2 masses whose physical and kinetic parameters are entirely defined for a simulation between 0 and 20 with 500 time steps.

 

6./ Menus, toolbar and status bar

Among all the menus only the File menu, the Window menu and the Help menu are currently available.

The toolbar provides shortcuts for the "Reset", "load system", "save as system" functions.

The status bar is and remains empty for now. It will be used to display information on the state of COSMIX (especially during calculations) and automatic help to the user.