Input/Output

Here is a documentation for functions related to saving simulation state and data files, based on the provided source code:

Saving Simulation Data

The PeriDyn package provides several functions for saving simulation data to files. These functions allow you to store the state of your simulations at various points during the simulation, which can be useful for post-processing, visualization, and analysis.

File Path Generation

The filepath_ function generates the path to the output folder for your simulation data.

• filepath_(file_prefix::String; append_date=false)

  • Arguments:
    • file_prefix: A string representing the prefix of the output folder.
  • Keyword Arguments:
    • append_date: A boolean value indicating whether to append the current date and time to the output folder name. Defaults to false.
  • Returns:
    • A string representing the full path to the output folder. The function also creates the folder if it doesn't exist.
  • Example:

filepath_("my_simulation_data", append_date = true)
# Returns: "my_simulation_data_2023-10-26T16-35-12/" 
# (assuming the current date and time is 2023-10-26 16:35:12)

Saving Simulation State

The save_state! and save_state_ovito_bc! functions save the state of your simulation environment to a file.

• save_state!(filename, env; force=false)

  • Arguments:
    • filename: A string representing the name of the file to save the data to.
    • env: A GeneralEnvironment object representing the simulation environment to be saved.
  • Keyword Arguments:
    • force: A boolean value indicating whether to force saving to data file format even if the data size is large. Defaults to false. If set to false and the data size is large, the function automatically switches to the more efficient .jld2 format.
  • This function saves the following data for each particle in the simulation:
    • id
    • type
    • position
    • velocity
    • acceleration
    • mass
    • volume
    • damage
  • Example:

save_state!("my_simulation_state.data", env)

• save_state_ovito_bc!(filename, env; force=false)
  • This function works similarly to save_state! but it encodes the boundary condition information into the particle types. This is particularly useful if you plan to visualize the simulation data in Ovito, as it allows you to distinguish between particles belonging to different boundary conditions.
  • Example:

save_state_ovito_bc!("my_simulation_state.data", env)

Saving Global Data

The write_global_data function saves global simulation data to a .jld2 file.

• write_global_data(filename; kwargs...)
  • Arguments:
    • filename: A string representing the name of the .jld2 file.
    • kwargs...: Keyword arguments representing the global data to be saved. The keys should be symbols, and the values should be arrays or other serializable objects.
  • Example:

write_global_data("global_data.jld2", total_energy = energy_history, total_momentum = momentum_history)

Saving Data at Intervals

The print_data_file! function saves both the simulation state and global data to separate files at specified intervals during the simulation.

• print_data_file!(envs::Array{GeneralEnvironment}, file_prefix::String, i::Int64)
  • Arguments:
    • envs: An array of GeneralEnvironment objects representing the simulation environments.
    • file_prefix: A string representing the prefix for the output files.
    • i: An integer representing the current step number.
  • This function automatically appends the environment ID and step number to the file names.
  • Example:

print_data_file!([env1, env2], "simulation_data", 10) 
# Creates files like "simulation_data/env_1_step_10.jld2", 
# "simulation_data/env_2_step_10.jld2", etc.

Data File Formats

The save_state!, save_state_ovito_bc!, and print_data_file! functions can save data in either .data or .jld2 format.

• The .data format is a simple text-based format that is compatible with Ovito. However, it can be inefficient for large simulations.
• The .jld2 format is a binary format that is more efficient for storing large amounts of data.

By default, these functions will attempt to save data in .data format unless the force keyword argument is set to true or the data size exceeds a certain threshold. In those cases, the functions will automatically switch to .jld2 format. You can also explicitly specify the desired file format by using the appropriate file extension (e.g., ".data" or ".jld2") in the filename argument.