inputfile module

Class responsible of writing the input file fed into gprMax

class src.dataset_creation.inputfile.InputFile(file_path: str | Path, title: str)

Bases: object

Class responsible of writing the input file fed into gprMax. Provides various convenience methods to write different sections of the file.

Can be used as a context manager:

>>> with Inputfile(...) as f:

this will automatically close the file at the end of the context.

Parameters:

file_pathstr or Path

the path at which to create the input file

titlestr

the title of the file (to write into the ‘title’ command to gprMax)

Methods

close()	Flush the file to disk and close it.
sample_randomized_metadata(config[, seed])	Samples all the random variables necessary for the randomization of the input file..
write_ballast(ballast_material, position[, ...])	Write to file the commands related to ballast stones and its associated fouling.
write_box_material(name, material, position)	Writes the commands associated with a box material.
write_command(command, args)	Write the specified command to file, together with its arguments.
write_fractal_box_material(name, material, ...)	Writes the commands associated with a fractal box material.
write_full_track(config, metadata)	Writes the commands relative to a full railway track on file.
write_general_commands(title, domain, ...)	Write the general commands to file.
write_line([line])	Write the line to file, followed by n.
write_materials(materials)	Writes multiple #material commands to file.
write_pss(pss_peplinski_material, position, ...)	Writes the pss layer into file.
write_rails()	Writes to file the rails.
write_randomized(config[, seed])	Writes an entire randomized gprMax input file on disk, based on the specified configuration.
write_save_geometry(objects_dir, view_dir)	Write the 'geometry_objects_write' and the 'geometry_view' commands to file.
write_sleepers(material, position, size[, ...])	Write to file the sleepers.
write_snapshots(output_basefilename, time_steps)	Write snapshot commands to file.
write_source_receiver(waveform_name, ...)	Writes the source and receiver commands to file.

close()

Flush the file to disk and close it.

sample_randomized_metadata(config: GprMaxConfig, seed: int | None = None)

Samples all the random variables necessary for the randomization of the input file..

Samples a variety of factors depending on the configuration provided:

• the kind of track between a regular PSS, AC rail and gravel-sand subgrade.

• the layer sizes with a beta distribution between the given bounds.

• fouling level with a beta distribution, if > fouling_box_threshold the track is considered fouled.

• general water content between 0 and 1 with a beta distribution.

• water infiltrations between the layers with a normal distribution centered on the

  general water content. They are added if the value > water_infiltration_threshold.

• general deterioration of the sub-ballast layers, with a beta distribution.

• sub-ballast layer water ranges with a normal distribution centered on the

  general water content.

• sleepers materials and position.

• ballast simulation seed.

Parameters:

configGprMaxConfig

configuration.

seedint | None, optional

seed to use in the random number generators. The input file contents are deterministic as long as the same seed is used.

Returns:

Metadata

The sampled metadata information

write_ballast(ballast_material: tuple[float, float, float, float], position: tuple[float], simulation_seed: Generator | int = None, fouling_level: float = 0.0)

Write to file the commands related to ballast stones and its associated fouling.

The ballast position is generated on the fly, using a pymunk simulation. See src.dataset_creation.ballast_simulation.BallastSimulation.

Parameters:

ballast_materiallist | tuple

material composing the ballast.

positiontuple[float]

initial and final height in meters of the ballast layer from the bottom of the model.

simulation_seednp.Generator | int, default: None

the custom seed to use for the ballast simulation.

fouling_levelfloat, default: 0

fouling level in the interval [0, 1] that determines the size of the ballast. A higher fouling_level corresponds to smaller ballast stones, on average. The precise distribution is obtained by linear interpolation between the values of a clean and fouled ballast.

write_box_material(name: str, material: list | tuple, position: tuple[float, float])

Writes the commands associated with a box material.

Parameters:

namestr

the name of the material

materiallist | tuple

the material phisical values

positiontuple[float, float]

initial and final y coordinate of the box

write_command(command: str, args: Iterable)

Write the specified command to file, together with its arguments.

Parameters:

commandstr

the command name, whithout ‘#’

argsIterable

an iterable of arguments to append to the command. These will be cast into strings

write_fractal_box_material(name: str, material: list | tuple, position: tuple[float, float], fractal_dimension: float, soil_number: int, top_surface_roughness: None | float = None, bottom_surface_roughness: None | float = None, add_top_water: bool = False, add_bot_water: bool = False)

Writes the commands associated with a fractal box material.

Can add top or bottom surface roughness and water

Parameters:

namestr

the name of the material

materiallist | tuple

the material phisical values, either 4 or 6 float values associated with normal or peplinski materials

positiontuple[float, float]

initial and final y coordinate of the box

fractal_dimensionfloat

fractal dimension of the box

soil_numberint

number of soil components, must be 1 if the material is not a peplinski soil.

top_surface_roughnessNone | float, default: None

max depth of the applied top surface roughness, not applied if None.

bottom_surface_roughnessNone | float, default: None

max height of the applied bottom surface roughness, not applied if None.

add_top_waterbool, default: False

if set, add top water until the max height of the top surface roughness.

add_bot_waterbool, default: False

if set, add bottom water until min height of the bottom surface roughness.

write_full_track(config: GprMaxConfig, metadata: Metadata)

Writes the commands relative to a full railway track on file.

Parameters:

configGprMaxConfig

configurationMetadata

metadataMetadata

Metadata containing all the randomly sampled values.

Returns:

Metadata

the original metadata object, extended with the calculated fouling, pss and subsoil materials.

write_general_commands(title: str, domain: tuple[float, float, float], spatial_resolution: tuple[float, float, float], time_window: float, output_dir: str | Path)

Write the general commands to file.

Parameters:

titlestr

the simulation’s title

domaintuple[float, float, float]

domain size of the simulation (in meters)

spatial_resolutiontuple[float, float, float]

spatial resolution of the simulation (in meters)

time_windowfloat

duration of the simulation for each A-scan (in seconds)

output_dirstr | Path

output directory

write_line(line: str = '')

Write the line to file, followed by n.

Parameters:

linestr, optional

line to write, default: “”

write_materials(materials: list[tuple[str, tuple[float, float, float, float]]])

Writes multiple #material commands to file.

Parameters:

materialslist[tuple[str, tuple[float]]]

list containing the materials. Each material is represented as a tuple of (name, properties), where properties is a tuple containing the 4 physical properties of the material.

write_pss(pss_peplinski_material: list | tuple, position: tuple[float, float], fractal_dimension: float, pep_soil_number: int)

Writes the pss layer into file.

Parameters:

pss_peplinski_materiallist | tuple

peplinski material for the PSS layer

positiontuple[float, float]

start and end y of the PSS layer.

fractal_dimensionfloat

fractal dimension of the box representing the PSS.

pep_soil_numberint

number of different peplinski fractal materials composing the PSS layer.

write_rails()

Writes to file the rails. Not implemented.

Raises:

NotImplementedError

Not implemented.

write_randomized(config: GprMaxConfig, seed: int | None = None)

Writes an entire randomized gprMax input file on disk, based on the specified configuration.

Equivalent to calling sample_randomized_metadata(), then write_full_track() with its results.

Parameters:

configGprMaxConfig

configuration.

seedint | None, optional

seed to use in the random number generators. The input file contents are deterministic as long as the same seed is used.

Returns:

Metadata

object containing information about the sampled values.

write_save_geometry(objects_dir: str | Path, view_dir: str | Path)

Write the ‘geometry_objects_write’ and the ‘geometry_view’ commands to file.

Parameters:

objects_dirstr | Path

directory in which to place the geometry object files. Not created if None.

view_dirstr | Path

directory in which to place the geometry view file. Not created if None.

write_sleepers(material: list | tuple, position: list[tuple], size: tuple[float, float, float], material_name: str = None)

Write to file the sleepers.

Parameters:

materiallist|tuple

material composing the sleepers.

positionlist[tuple]

list of (x,y,z) position of the sleepers in meters, representing their bottom-left corner.

sizetuple[float, float, float]

(x, y, z) size of the sleepers in meters.

material_namestr, default: None

name of the sleepers material.

write_snapshots(output_basefilename: str | Path, time_steps: list[float])

Write snapshot commands to file.

Parameters:

output_basefilenamestr | Path

output filename, the snapshots are automatically saved in the ‘{input_file_name}_snaps{n}’ folder, where n is the model run (A-scan number).

time_stepslist[float]

times at which to take the snapshots, in seconds.

write_source_receiver(waveform_name: str, source_central_frequency: int | float, source_position: tuple[float, float, float], receiver_position: tuple[float, float, float], step_size: tuple[float, float, float])

Writes the source and receiver commands to file.

Parameters:

waveform_namestr

name of the waveform, e.g. ‘ricker’, ‘gaussian’…

source_central_frequencyint|float

central frequency of the source waveform.

source_positiontuple[float, float, float]

position of the source hertzian dipole in space.

receiver_positiontuple[float, float, float]

position of the receiver in space.

step_sizetuple[float, float, float]

space increments to move the source and receiver between the different A-scans.