ballast_simulation module

class src.dataset_creation.ballast_simulation.BallastSimulation(domain_size: tuple[float, float], radii_distribution: ndarray = None, buffer_y: float = 0, verbose: bool = False)[source]

Bases: object

Class responsible to create and run a 2D physics simulation for generating realistic ballast positions and radii.

First samples a specific distribution of ballast radii from the given intervals, then uses the Random Sequential Absorption algorithm to randomly create the ballast stones inside the space, then runs a pymunk gravity simulation to compact the agglomerates.

Parameters:

domain_sizetuple[float, float]: (x, y) size of the simulation.
radii_distributionnp.ndarray, default: None: radii distribution to use in the RSA algorithm. If None, the default distribution will be used
buffer_yfloat, default: 0: bonus y size of the simulation to account for compacting the voids. Not shown in the visualization
verbosebool: if True, print debug info. Default: False

Methods

`get_clean_ballast_radii_distrib`()	Returns the radii distribution for clean ballast without fouling.
`get_fouled_ballast_radii_distrib`()	Returns the radii distribution for very fouled ballast.
`random_sequential_adsorption`(space, ...[, ...])	Use the Random Sequential Absorption algorithm to randomly create the ballast stones inside the space.
`run`([running_time, time_step, display, ...])	Run the siumlation.
`sample_radii_distribution`(...)	Picks a random radii distribution.

classmethod get_clean_ballast_radii_distrib() → ndarray[source]

Returns the radii distribution for clean ballast without fouling.

Returns:

np.ndarray: The radii distribution

classmethod get_fouled_ballast_radii_distrib() → ndarray[source]

Returns the radii distribution for very fouled ballast.

Returns:

np.ndarray: The radii distribution

random_sequential_adsorption(space: Space, required_void: float, mult_factor: float, random_seed: Generator | int = None) → Space[source]

Use the Random Sequential Absorption algorithm to randomly create the ballast stones inside the space.

Parameters:

spacepymunk.Space: space in which to place the circles.
required_voidfloat: fraction of void surface to fill before returning.
mult_factorfloat: multiplication factor to use in the pymunk space for visualization purposes.
random_seednp.random.Generator | int, default: None: random seed for the generator to use in the RSA algorithm. If None, creates a new generator.

Returns:

pymunk.Space: the input space, with all the new circles added to it.

run(running_time: float = 2, time_step: float = 0.002, display: bool = False, random_seed: Generator | int = None)[source]

Run the siumlation.

First generates circular ballast stones positions and radii by using a random sequential absorption (RSA) algorithm, then uses a 2D physics simulation from pymunk to aggregate them.

Parameters:

running_timefloat: length of (simulated) time to run the simulation for. Bigger values make sure that the circles are compacted, but require more computation.
time_stepfloat (optional): time step at which to run the simulation. Smaller steps mean more precise simulation, but more computations.
displaybool, default: False: Flag to set if the simulation should be displayed inside a pygame window.
random_seednp.random.Generator | int, default: None: random seed to use in the generator for the RSA algorithm. If None, creates a new generator.

Returns:

np.ndarray of shape [n_circles, 3]: Circle positions and radii: each item is of the form [x_position, y_position, radius]

sample_radii_distribution(sieve_diameter_bounds: ndarray, random_generator: Generator) → ndarray[source]

Picks a random radii distribution.

The distribution is picked from the diameter bounds provided by sampling from a beta distribution for each sieve.

Parameters:

sieve_diameter_boundsnp.ndarray of shape (n_sieves, 3)

sieve diameters and mass lower and upper bounds for each sieve, eg:

[[0.06, 0.9, 1.0], [0.04, 0.5, 0.9], [0.02, 0.1, 0.5]]

means three sieves of diameter 0.06, 0.04, 0.02, where each entry is [sieve_diameter, mass_lower_bound, mass_upper_bound]

random_generatornp.random.Generator

random generator to use for the sampling

Returns:

np.ndarray of shape (n_sieves - 1, 3): the sampled distribution, where each entry is [radius_max, radius_min, required_mass]. The required masses sum to 1.