FreeBirdIO

FreeBirdIO

Module for input/output operations in the FreeBird package.

abstract type DataSavingStrategy

Abstract type representing a strategy for saving data.

struct SaveEveryN <: DataSavingStrategy

SaveEveryN is a concrete subtype of DataSavingStrategy that specifies saving data every N steps.

Fields

• df_filename::String: The name of the file to save the DataFrame to.
• wk_filename::String: The name of the file to save the atom walker to.
• ls_filename::String: The name of the file to save the liveset to.
• n_traj::Int: The number of steps between each save of the culled walker into a trajectory file.
• n_snap::Int: The number of steps between each save of the liveset into a snapshot file.
• n_info::Int: The number of steps between each print of information.

struct SaveFreePartEveryN <: DataSavingStrategy

SaveFreePartEveryN is a concrete subtype of DataSavingStrategy that specifies saving data every N steps. Only the free particles are saved into the trajectory and snapshot files.

Fields

• df_filename::String: The name of the file to save the DataFrame to.
• wk_filename::String: The name of the file to save the atom walker to.
• ls_filename::String: The name of the file to save the liveset to.
• n_traj::Int: The number of steps between each save of the culled walker into a trajectory file.
• n_snap::Int: The number of steps between each save of the liveset into a snapshot file.
• n_info::Int: The number of steps between each print of information.

append_system(ats1::FlexibleSystem, ats2::FlexibleSystem)

Append two FlexibleSystem objects into a single FastSystem object. The first argument is the system to be appended to, and its bounding box and boundary conditions will be used for the new system.

Arguments

• ats1::FlexibleSystem: The base system to be appended.
• ats2::FlexibleSystem: The system to append.

Returns

• new_list: A new FastSystem object containing the appended systems.

append_system(ats1::FlexibleSystem, ats2::Vector{FlexibleSystem})

Append a FlexibleSystem object to a vector of FlexibleSystem objects. The first argument is the system to be appended to, and its bounding box and boundary conditions will be used for the new systems.

Arguments

• ats1::FlexibleSystem: The base system to be appended.
• ats2::Vector{FlexibleSystem}: A vector of FlexibleSystem objects to append.

Returns

• configs: A vector of FastSystem objects containing the appended systems.

append_walker(filename::String, at::AtomWalker)

Append an AtomWalker object to a file.

convert_system_to_walker(at::FlexibleSystem, resume::Bool)

Converts a FlexibleSystem object to an AtomWalker object.

Arguments

• at::FlexibleSystem: The FlexibleSystem object to convert.
• resume::Bool: Whether to resume from previous data.

Returns

• AtomWalker: The converted AtomWalker object.

convert_walker_to_system(at::AtomWalker)

Converts an AtomWalker object to an AbstractSystem object.

Arguments

• at::AtomWalker: The AtomWalker object to be converted.

Returns

• AbstractSystem: The converted AbstractSystem object.

generate_initial_configs(num_walkers::Int, volume_per_particle::Float64, num_particle::Int; particle_type::Symbol=:H)

Generate initial configurations for a given number of walkers.

Arguments

• num_walkers::Int: The number of walkers.
• volume_per_particle::Float64: The volume per particle.
• num_particle::Int: The number of particles.
• particle_type::Symbol=:H: The type of particle (default is :H).

Returns

An array of initial configurations for each walker.

generate_initial_configs(num_walkers::Int, volume_per_particle::Float64, num_particle::Vector{Int}; particle_types::Vector{Symbol}=[Symbol(:H), Symbol(:O)])

Generate initial configurations for a given number of walkers with multiple particle types.

Arguments

• num_walkers::Int: The number of walkers.
• volume_per_particle::Float64: The volume per particle.
• num_particle::Vector{Int}: A vector containing the number of particles of each type.
• particle_types::Vector{Symbol}=[Symbol(:H), Symbol(:O)]: A vector of symbols representing the types of particles (default is hydrogen and oxygen).

Returns

An array of initial configurations for each walker, where each configuration contains particles of the specified types.

generate_lattice_starting_config(box_length::Float64, num_particle::Int;
                                 particle_type::Symbol=:H,
                                 periodicity::NTuple{3,Bool}=(true, true, true),
                                 jitter::Float64=0.0)

Generate a starting configuration on a simple-cubic grid: the first num_particle cell-centered sites of the smallest grid containing them, with an optional uniform jitter of up to jitter Å per coordinate. Deterministic at jitter = 0. Covers densities beyond the sequential-insertion regime of generate_random_starting_config (dense-liquid and solid-like starts for Metropolis annealing); the pairwise separation is at least the grid spacing minus 2 √3 jitter. The same nested-sampling scoping applies: this is not a prior draw and must not seed a nested-sampling live set.

Arguments

• box_length::Float64: The cubic box edge in Å.
• num_particle::Int: The number of particles.
• particle_type::Symbol=:H: The type of particle.
• periodicity::NTuple{3,Bool}=(true, true, true): Per-axis boundary conditions.
• jitter::Float64=0.0: Uniform per-coordinate displacement bound in Å.

Returns

• FastSystem: A FastSystem object representing the generated system.

generate_multi_type_random_starting_config(volume_per_particle::Float64, num_particle::Vector{Int}; particle_types::Vector{Symbol}=[Symbol(:H), Symbol(:O)])

Generate a random starting configuration for a system of particles with multiple types.

Arguments

• volume_per_particle::Float64: The volume per particle.
• num_particle::Vector{Int}: The number of particles of each type.
• particle_types::Vector{Symbol}=[Symbol(:H), Symbol(:O)]: The types of particles.

Returns

• FastSystem: A FastSystem object representing the generated system.

generate_random_starting_config(volume_per_particle::Float64, num_particle::Int;
                                particle_type::Symbol=:H,
                                periodicity::NTuple{3,Bool}=(false, false, false),
                                min_separation::Float64=0.0,
                                max_attempts::Int=1000)

Generate a random starting configuration for a system of particles.

Intended for Metropolis and grand-canonical Metropolis starting states and reference-run inputs. Nested-sampling live sets must remain i.i.d. draws from the sampling prior: a minimum-separation draw is not the uniform prior, and a non-prior initial live set biases the nested-sampling evidence (see the initialization note in test/test-SamplingSchemes/test-atomistic-gcns-fixed-n.jl).

Arguments

• volume_per_particle::Float64: The volume per particle.
• num_particle::Int: The number of particles.
• particle_type::Symbol=:H: The type of particle (default is hydrogen).
• periodicity::NTuple{3,Bool}=(false, false, false): Per-axis boundary conditions of the generated system. The default keeps the historical non-periodic behavior.
• min_separation::Float64=0.0: Minimum pairwise separation in Å, enforced by sequential insertion with per-particle retries. Distances are minimum-image on periodic axes and plain Euclidean otherwise. The default performs no separation screening and consumes exactly the historical random stream.
• max_attempts::Int=1000: Retry budget per particle; exhaustion throws an ArgumentError reporting the attempted packing fraction.

Returns

• FastSystem: A FastSystem object representing the generated system.

read_configs(filename::String, pbc::Vector)

Reads atomic configurations from a file and applies periodic boundary conditions.

Arguments

• filename::String: The name of the file containing the atomic configurations.
• pbc::Vector: A vector specifying the periodic boundary conditions.

Returns

An array of atomic configurations with periodic boundary conditions applied.

read_configs(filename::String; pbc::String="TTT")

Reads configurations from a file.

Arguments

• filename::String: The name of the file to read configurations from.
• pbc::String="TTT": Periodic boundary conditions. A string of length 3, where each character represents whether the corresponding dimension has periodic boundary conditions ('T') or not ('F').

Returns

• The configurations read from the file.

read_single_config(filename::String, pbc::Vector)

Reads a single configuration from the specified file and sets the periodic boundary conditions (PBC) for the atoms.

Arguments

• filename::String: The name of the file to read the configuration from.
• pbc::Vector: A vector specifying the periodic boundary conditions.

Returns

• at::Atoms: The atoms with the PBC set.

read_single_config(filename::String; pbc::String="TTT")

Reads a single configuration from the specified file.

Arguments

• filename::String: The name of the file to read from.
• pbc::String="TTT": The periodic boundary conditions. Default is "TTT".

Returns

• The configuration read from the file.

read_single_walker(filename::String; pbc::String="TTT", resume::Bool=true)

Reads a single walker from the specified file.

Arguments

• filename::String: The path to the file containing the walker data.
• pbc::String: (optional) The periodic boundary conditions. Default is "TTT".
• resume::Bool: (optional) Whether to resume reading from a previous checkpoint. Default is true.

Returns

• The walker object read from the file.

read_walkers(filename::String; pbc::String="TTT", resume::Bool=true)

Reads walker configurations from a file.

Arguments

• filename::String: The name of the file to read the walker configurations from.
• pbc::String: A string specifying the periodic boundary conditions. Default is "TTT".
• resume::Bool: A boolean indicating whether to resume reading from a previous checkpoint. Default is true.

Returns

An array of walker objects.

set_pbc(at::Atoms, pbc::Vector)

Set the periodic boundary conditions for a system of atoms.

Arguments

• at::Atoms: The system of atoms.
• pbc::Vector: A vector of length 3 specifying the periodic boundary conditions for each dimension. Each element can be either true for periodic boundary conditions or false for Dirichlet zero boundary conditions.

Returns

• FlexibleSystem: A flexible system with the specified boundary conditions.

write_df(filename::String, df::DataFrame)

Write a DataFrame to a CSV/Arrow file.

Arguments

• filename::String: The name of the file to write to.
• df::DataFrame: The DataFrame to write.

write_df_every_n(df::DataFrame, step::Int, d_strategy::SaveEveryN)

Write the DataFrame df to a file specified by d_strategy.filename every d_strategy.n steps.

Arguments

• df::DataFrame: The DataFrame to be written.
• step::Int: The current step number.
• d_strategy::SaveEveryN: The save strategy specifying the filename and the step interval.

write_ls_every_n(ls::AtomWalkers, step::Int, d_strategy::SaveEveryN)

Write the liveset ls to file every n steps, as specified by the d_strategy.

Arguments

• ls::AbstractLiveSet: The liveset to be written.
• step::Int: The current step number.
• d_strategy::SaveEveryN: The save strategy specifying the frequency of writing.

write_single_walker(filename::String, at::AtomWalker, append::Bool)

Write a single AtomWalker object to a file. If the file already exists, append the walker to the file.

Arguments

• filename::String: The name of the file to write to.
• at::AtomWalker: The AtomWalker object to write.
• append::Bool: A boolean indicating whether to append the walker to the file if it already exists.

write_single_walker(filename::String, at::AtomWalker)

Write a single AtomWalker object to a file.

Arguments

• filename::String: The name of the file to write to.
• at::AtomWalker: The AtomWalker object to write.

write_walker_every_n(wk::AbstractWalker, step::Int, d_strategy::SaveEveryN)

Write the walker wk to a file specified by d_strategy.wk_filename every d_strategy.n steps.

Arguments

• wk::AbstractWalker: The walker to be written.
• step::Int: The current step number.
• d_strategy::SaveEveryN: The save strategy specifying the file name and the interval.

write_walkers(filename::String, ats::Vector{AtomWalker})

Write a collection of AtomWalker objects to a file.

Arguments

• filename::String: The name of the file to write the walkers to.
• ats::Vector{AtomWalker}: The collection of AtomWalker objects to write.

write_walkers(filename::String, ats::Vector{LatticeWalker})

Write a collection of LatticeWalker objects to a file.

Arguments

• filename::String: The name of the file to write the walkers to.
• ats::Vector{LatticeWalker}: The collection of LatticeWalker objects to write.