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.

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

You must also define BALL0_SPEED (launch speed), BALL0_VEL_ANGLE (launch angle: 90°), BALL0_TIME (orbit activation time), BALL0_DELTA_SPEED (orbital speed), and BALL0_DELTA_ANGLE (initial orbital angle: 0°).

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

(Beginning of file)

(End of file)

Based on the parameters above, you must define BALL0_SPEED (initial launch speed), BALL0_TIME (orbit activation time), and BALL0_DELTA_SPEED (second velocity, i.e., orbital speed). The initial launch angle is BALL0_VEL_ANGLE 90, and the angle of the second velocity is BALL0_DELTA_ANGLE 0.

Tip: set BALL0_DELTA_SPEED to zero, but BALL0_TIME large enough for the ball to reverse its velocity. Observe the printed data—the resulting altitude will become evident.

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!