I) Instructions to create the "Parameters.txt" file

It is possible to program the simulation parameters through a text file.

There are two options to create the parameter file:

1) Create a "Parameters.txt" file to program the simulation parameters. You can build this file by following the instructions below.

2) Automatically create and save a default "Parameters.txt" file with the simulation “Three balls (default)”, then edit that file and change the variable values to create your custom simulation, saving it as a new “*.txt” file. Use option (3) in the menu.

Use any text editor, but always save as plain text “.txt” (without formatting). You may choose another filename and create different files for each simulation.

After creating the file, load it by selecting option (1) in the menu, and then you can run your specific simulations.

The file must contain all variables (36 in total). Each variable must be on its own line in the format [the variable, one or more spaces, and the value], as in the model:

VARIABLE value

Example:

NBALLS 2

This means we are defining the parameter “NBALLS”, the number of balls in the simulation, with value “2”.

Note: the maximum number of balls depends on the capacity of your computer, but internally it is limited by the size of the integer type (32767). We have not tested or programmed for extreme conditions.

Example:

BALL_MASS 1.0

This sets the “BALL_MASS” parameter, the mass of the balls in the simulation, with value “1.0”.

Below is a full example of all the parameters, with the configuration to initialize the “Three balls (default)” simulation (option 1 in the menu):

(Beginning of file)

(End of file)

Please do not write “(Beginning of file)” and “(End of file)”. Write only the variable names and values of all 36 variables, with optional blank lines between related groups. These blank lines are optional; you may remove or add them to make the blocks clearer.

Suggestion: 1) Select the entire parameter area above. 2) Right‑click and choose “Copy”. 3) Go to your text editor and choose “Paste” (as text). The file will still be read correctly even if spaces appear before each variable. 4) Save the file in “.txt” format.

Next, we explain each group and variable.

The first group is:

This group contains the simulation mode (GAS_MODE x), number of balls (NBALLS x), ball radius (BALL_RADIUS x), initial velocity (BALL_SPEED x), mass of each ball (BALL_MASS x.x), gravity applied to the balls (BALL_GRAVITY x), gravitational constant (BALL_G x), collision mode (PUSH_PULL x), and coefficient of restitution for partially inelastic simulations (COEF_RESTITUTION x.x). PUSH_PULL is an internal configuration (default: “1”).

The next group has three blocks and begins with IS_TESTING:

When IS_TESTING = “1”, the simulation reads the parameters for balls 0 and 1. They control positions, sizes, masses and initial velocities (magnitude and angle). This is useful for tests and for simulations such as “satellite launching”.

For ball 0, you may define a “second velocity” (delta speed), added at a specific instant, using BALL0_TIME, BALL0_DELTA_SPEED, and BALL0_DELTA_ANGLE.

Note: BALL0_TIME represents time in milliseconds.

In the “Three balls (default)” simulation, IS_TESTING = 0, so these parameters are ignored. In other use cases, however, they are essential.

We will now see the “Satellite launching” example.

After these blocks, the next group is:

This group defines the piston mass (PISTON_MASS x) and the gravity applied to the piston (PISTON_GRAVITY x.x).

The next group is:

This corresponds to an approximate “energy injection” simulation from the bottom, controlling how much energy can be inserted using the → and ← keys.

The final group is:

This shows the rendering options such as the drawing area size in pixels (SCREEN_WIDTH, SCREEN_HEIGHT) and background color (BACKGROUND), with options “0” and “1”. PERCENT_WIDTH and PERCENT_HEIGHT define the fraction of space occupied by the cylinder. ZOOM_FACTOR creates a zoom effect to fit large areas on the screen.

----

II) Elementary simulation: “Satellite launching”

As a challenge, you can determine the parameters for an elementary satellite launch. Set NBALLS 2 and IS_TESTING 1 to program the first two balls: the planet and the satellite.

Define their sizes (BALL0_RADIUS and BALL1_RADIUS), masses (BALL1_MASS, BALL0_MASS) and positions (BALL0_X, BALL0_Y, BALL1_X, BALL1_Y).

It will also be necessary to define BALL0_SPEED (the launch velocity), BALL0_VEL_ANGLE (the launch angle, set to 90 degrees), BALL0_TIME (the moment of orbital insertion, when the orbital velocity should be applied), BALL0_DELTA_SPEED (the orbital velocity, which will be added to the current velocity at that instant), and BALL0_DELTA_ANGLE (the angle of the orbital velocity to be added, set to 0 degrees).

Example of “Satellite launching” (three values omitted with xxx):

(Beginning of file)

(End of file)

Based on the parameters above, you will need to program BALL0_SPEED (the initial velocity at satellite launch), BALL0_TIME (the moment when the orbital velocity will be added, in milliseconds), and BALL0_DELTA_SPEED (the value of the orbital velocity to be added). Note that the suggested initial launch angle is defined as BALL0_VEL_ANGLE 90, and the orbital velocity angle as BALL0_DELTA_ANGLE 0.

Recommendation: Set BALL0_DELTA_SPEED to zero and assign BALL0_TIME a value corresponding to a moment after the inversion of the satellite’s velocity direction, once it has reached a complete stop*. Analyze the data printed by the program to identify the maximum altitude reached.

*Note: the program will display auxiliary information only when the specified BALL0_TIME condition is met.

----

III) Partially inelastic collision

The “IS_TESTING 1” configuration is also useful to simulate the collision of two balls and study the effect of the coefficient of restitution. Simply set NBALLS 2 and adjust the other parameters. Below is an example:

(Beginning of file)

(End of file)

Observe the coefficient of restitution and how the parameters after IS_TESTING 1 were configured. Ball 0 is programmed to collide with ball 1.

Enjoy your simulations!