ball create command

Syntax

ball create keyword ...

Primary keywords:

group    id    position    radius    position-x    position-y    position-z

Create a single ball with the specified attributes.

Note

• A model domain must be specified prior to ball creation.
• While cycling, balls can only be created before cycle point 0 (i.e., when the timestep is calculated).

group s <slot slot > ...

The group slot slot is set to s for the newly created ball. If the slot keyword is not specified, then the group name is assigned to the slot with name Default.

id i

Ball ID. If not specified, then the next available ID is used. An error is raised if a ball with the specified ID already exists in the system.

position v

Ball position that is the origin by default.

radius f

Ball radius. If not specified, the ball is created with a radius equal to 1/40th of the minimum domain extent. A value larger-than or equal to 1/4th of the minimum domain extent is not allowed.

position-x f

The \(x\)-component of the position that is 0 by default.

position-y f

The \(y\)-component of the position that is 0 by default.

position-z f (3D ONLY)

The \(z\)-component of the position that is 0 by default.

Usage Example

The ball create command is one of the three commands that can be used to create balls. Alternative commands are ball generate and ball distribute. As discussed in the command description above, ball create command can be used to create a single ball.

Using the default parameters, a ball with the next ID available and a radius equal to 1/40th of the minimum domain extent will be created at the origin:

model domain extent -10.0 10.0
ball create

Figure 1: Using default parameters, the ball create command creates a ball with a radius equal to 1/40th of the minimum domain extent, located at the origin.

The default parameters may be overridden to control the outcome of the command. In the following example, three balls are created using the ball create command three times consecutively. The first ball is created at x = -5.0 (with the default radius); the second ball is created at x = 5.0 with a radius of 4.0; and the last ball is created at the origin (by default) with an ID of 10, a radius of 1.0, and with a group assigned.

model domain extent -10.0 10.0
ball create position-x -5.0
ball create position-x  5.0 radius 4.0
ball create id 10 position-x  0.0 radius 1.0 group 'middle'

Figure 2: Overriding the default parameter allows full control on the command behavior.

As shown in the example above, multiple balls can be created by repeating the ball create command. The tutorial example “Using FISH Callbacks” demonstrates how this command can be issued periodically to create balls at a given frequency.

Alternatives to the ball create command are the ball generate and ball distribute commands, which are designed to generate an assembly of balls at once.

See also

ball generate | ball distribute