pymatnest module

ns_run.accumulate_stats(d_cumul, d)[source]
ns_run.add_to_list(list, ind, costs, nums, walk_len_avail, first_free_slot)[source]
ns_run.additive_init_config(at, Emax)[source]
ns_run.adjust_step_sizes(walk_stats, movement_args, comm, do_print_rate=True, monitor_only=False)[source]

Adjust step size to keep the acceptance ratio at the desired level.

ns_run.clean_prev_snapshot(iter)[source]
ns_run.create_list(costs, nums, walk_len)[source]
ns_run.do_MC_atom_velo_walk(at, movement_args, Emax, nD, KEmax)[source]
ns_run.do_MC_atom_walk(at, movement_args, Emax, KEmax)[source]
ns_run.do_MC_cell_shear_step(at, movement_args, Emax, KEmax)[source]
ns_run.do_MC_cell_stretch_step(at, movement_args, Emax, KEmax)[source]
ns_run.do_MC_cell_volume_step(at, movement_args, Emax, KEmax)[source]
ns_run.do_MC_semi_grand_step(at, movement_args, Emax, KEmax)[source]
ns_run.do_MC_swap_step(at, movement_args, Emax, KEmax)[source]
ns_run.do_MD_atom_walk(at, movement_args, Emax, KEmax)[source]

perform MD walk on the configuration

ns_run.do_atom_walk(at, movement_args, Emax, KEmax)[source]
ns_run.do_cell_shape_walk(at, movement_args)[source]
ns_run.do_cell_step(at, Emax, p_accept, transform)[source]
ns_run.do_ns_loop()[source]

This is the main nested sampling loop, doing the iterations.

ns_run.energy_internal(at)[source]
ns_run.energy_internal_pos(pos, l)[source]
ns_run.eval_energy(at, do_KE=True, do_PE=True)[source]

Calls appropriate functions to calculate the potential energy, kinetic energy and the p*V term.

ns_run.eval_energy_KE(at)[source]
ns_run.eval_energy_PE(at)[source]
ns_run.eval_energy_PV(at)[source]
ns_run.eval_energy_mu(at)[source]
ns_run.eval_forces(at)[source]
ns_run.excepthook_mpi_abort(exctype, value, tb)[source]
ns_run.exit_error(message, stat)[source]
ns_run.full_auto_set_stepsizes(walkers, walk_stats, movement_args, comm, Emax, KEmax, size_n_proc)[source]

Automatically set all step sizes. Returns the time (in seconds) taken for the routine to run.

ns_run.gen_random_velo(at, KEmax, unit_rv=None)[source]
ns_run.internal_Vlj(dr_vec, Eshift=0.0)[source]
ns_run.main()[source]

Main function

ns_run.max_energy(walkers, n, kinetic_only=False)[source]

Collect the current energies of the walkers from all the processes and chooses the right number of highest energies to be culled

ns_run.min_aspect_ratio(vol, cell)[source]
ns_run.pairwise(iterable)[source]
ns_run.propagate_NVE_ASE(at, dt, n_steps)[source]
ns_run.propagate_lammps(at, dt, n_steps, algo, Emax=None)[source]
ns_run.propose_area_step(at, step_size, flat_V_prior)[source]
ns_run.propose_shear_step(at, step_size)[source]
ns_run.propose_stretch_step(at, step_size)[source]
ns_run.propose_volume_step(at, step_size, flat_V_prior)[source]
ns_run.rand_perturb_energy(energy, perturbation, Emax=None)[source]
ns_run.rej_free_perturb_velo(at, Emax, KEmax, rotate=True)[source]
ns_run.rotate_dir_3N(vec, max_ang)[source]
ns_run.rotate_dir_3N_2D(vec, max_ang)[source]
ns_run.save_snapshot(snapshot_id)[source]

Save the current walker configurations’ as a snapshot in the file out_file_prefix.iter.rank.config_file_format

ns_run.set_n_from_expected(prop)[source]
ns_run.str_to_logical(x)[source]
ns_run.usage()[source]

Print help to the standard output about the usage of the code and input parameters. The current list of parameters is the following:

max_volume_per_atom=float
Maximum volume per atom allowed during the run.
default: 1.0e3
min_volume_per_atom=float
Minimum volume per atom allowed during the run.
default: 1.0
start_species=int int [ float ] [, int int [ float ] ... ]
MANDATORY (or start_config_file)
Atomic number; multiplicity; [ not recommended: mass (amu) ]. Info repeated for each species, separated by commas, mass is optional and not recommended.
start_config_file=str
MANDATORY (or start_species)
Name of file to read in for atom information
default: ‘’
``keep_atoms_fixed=int ``
Number of atoms to fix in surface simulation.
``apply_Z_wall=[T|F] ``
Whether to have a boundary in the Z direction to keep free particles reaching the other side of “surface” layer due to periodic boundary conditions.
This functionality is not fully tested! Recommended use with MC evaluator and fortran. If constructing a surface layer, make it parallel to the XY plane and set the X dimension with the “wall” taken into account, no atoms should violate the wall restriction initially!!!
If True, the wall is set at 10 angstroms below the top of the simulation cell.
restart_file=path_to_file
File for restart configs. Mutually exclusive with start_*, one is required. The file should contain the state of the walkers to continue from along with the restart iteration number. Normally such a file can be the concatenated snapshot files.
n_walkers=int
MANDATORY
Total number of walkers, i.e. the size of the live set used. It has to be the multiple of the number of processors used and it also has to be larger than the number of processors.
n_cull=int
Number of walkers to kill at each NS iteration. Use of default 1 is strongly recommended.
deafult: 1
n_extra_walk_per_task=int
default: 0
n_iter_times_fraction_killed=int
MANDATORY
Number of nested sampling iteration cycles performed per walker. Thus the total number of iterations will be n_iter_times_fraction_killed / (n_cull/n_walkers). Either this or converge_down_to_T is required.
converge_down_to_T=flot
MANDATORY
temperature down to which Z(T) should be converged. Either this or n_iter_times_fraction_killed is required.
T_estimate_finite_diff_lag=int
default: 1000
Lag (in iterations) for doing d log Omega / d E finite difference derivative
min_Emax=float
Termination condition based on Emax: if this value is reached, the iteration will stop.
No default.
out_file_prefix=str
String used as prefix for the different output files.
No default.
energy_calculator= ( ASE | lammps | internal | fortran)
Energy calculator.
default: fortran
n_extra_data=int
Amount of extra data per atom to pass around.
default: 0
KEmax_max_T=float
If > 0, maximum temperature for estimating KEmax. For constant P ensemble 3/2 P Vmax will be used if KEmax_max_T is < 0.
default: -1
kB=float
Boltzmann constant
default: 8.6173324e-5 (eV/A)
start_energy_ceiling_per_atom=float
Maximum potential energy per atom for initial configurations. P*Vmax is added to this automatically in case of NpT runs.
default: 1.0e9
start_energy_ceiling=float
DEPRECATED: use start_energy_ceiling_per_atom. Maximum potential energy for initial configurations. P*Vmax is added to this automatically in case of NpT runs.
default: 1.0e9
random_init_max_n_tries=int
Maximum number of tries to create initial random atomic configuration
default 100
n_model_calls_expected=int
Total number of model calls performed during the random walk, expected by the user. The actual number of model calls performed during runtime can be different: this number is divided up among the processors in case of running parallel, and in order to make sure different processors perform about the same number of calls, it can be increased for some. (It is recommended to use n_model_calls_expected/[number of processors] > 20) Either this or the keyword n_model_calls is mandatory, but the use of this keyword is strongly recommended. If < 0, value will be set to _sum_ of each type of steps (accounting for atom_traj_len), so n_*_steps will be setting the _number_ of calls, rather than just the ratios.
default: 0
n_model_calls=int
Number of model calls performed during the random walk. This is the actual number of calls performed, ideally the program sets its value depending on n_model_calls_expected and the number of processors used. Either this or the keyword n_model_calls_expected is mandatory, though the usage of the latter is strongly recommended.
default: 0
do_good_load_balance=[T | F]
Whether to do steps in groups with good load balance
default: F
n_atom_steps=int
Ratio of atomic trajectories will be determined by n_atom_steps/SUM(n_*_steps).
default: 1
atom_traj_len=int
Length of atomic trajectory (MD steps or MC sweeps) in each atomic type step.
default: 8
atom_traj_len_cost_multiplier=int
Multiplier for cost of an atomic step (set to 1 for MD, TE-HMC, and SP-MC with O(1) cost moves, N for naive SP-MC)
default: 1
break_up_atom_traj=[T | F]
Whether to intersperse n_atom_steps atomic sub-trajectories with other types of steps.
default: F
n_cell_volume_steps=int
Ratio of cell volume steps will be determined by n_cell_volume_steps/SUM(n_*_steps).
default: 1
n_cell_shear_steps=int
Ratio of cell shear steps will be determined by n_cell_shear_steps/SUM(n_*_steps).
default: 1
n_cell_stretch_steps=int
Ratio of cell stretch steps will be determined by n_cell_stretch_steps/SUM(n_*_steps).
default: 1
n_swap_steps=int
Ratio of species swap steps will be determined by n_swap_steps/SUM(n_*_steps). It has to be set other than zero for a multicomponent system.
default: 0
swap_max_cluster=int
Maximum size of interconnected cluster to try to swap.
default: 1
swap_r_cut=float
Cutoff radius for defining connected atoms for cluster.
default: 2.5
swap_cluster_probability_increment=float
Factor between prob. of picking increasing larger clusters.
default: 0.75
swap_velo=[T | F]
If true, swap velocities when swapping atoms, breaking coherence a bit.
default: F
no_swap_velo_fix_mag_alt=[T | F]
If true, use alternate method for correcting velocity magnitudes when not swapping velocities.
default: F
n_semi_grand_steps=int
Ratio of species type-change steps will be determined by n_semi_grand_steps/SUM(n_*_steps). Only makes sense for a multicomponent system.
default: 0
``semi_grand_potentials=Z1
Chemical potentials for semi-grand canonical species-type transmutations
default: ‘’
velo_traj_len=int
Number of MC steps in (optional) explicit velocity MC trajectory.
default: 0
random_energy_perturbation=float
default: 1.0e-12
atom_algorithm=[MC | MD | GMC]
MANDATORY
Use either Monte Carlo or Molecular dynamics to explore. GMC is an alias for atom_algorithm=MC, MC_atom_Galilean=True.
MC_atom_velocities=[T | F]
This keyword is supported only for energy_calculator=fortran.
default: F
MC_atom_velocities_pre_perturb=[T | F]
Perturb velocities (rejection free) before MC + velocities walk.
default: F
MC_atom_step_size=float
Initial atom move step size in units of (max_volume_per_atom * N_atoms)^(1/3)
default: 1.0
MC_atom_step_size_max=float
Maximum atom step size in units of (max_volume_per_atom * N_atoms)^(1/3).
default: 1.0
MC_atom_uniform_rv=[T | F]
default: F
MC_atom_Galilean=[T | F]
default: F
GMC_no_reverse=[T | F]
default: T
MD_atom_velo_pre_perturb=[T | F]
Perturb velocities before MD trajectory
default: F
MD_atom_velo_post_perturb=[T | F]
Perturb velocities after MD trajectory
default: T
MD_atom_velo_flip_accept=[T | F]
default: F
MD_atom_timestep=float
default: 0.1 (ASE time units)
MD_atom_timestep_max=float
default: 2.0 (ASE time units)
MD_atom_energy_fuzz=float
Tolerance for rejecting non-energy conserving trajectories, as fraction of Kinetic Energy
default: 1.0e-2
MD_atom_reject_energy_violation=[ T | F ]
Use energy conservation violation (exceeding MD_atom_energy_fuzz * KE) to reject MD trajectories.
default: F
python_MD=[ T | F ]
Do MD using python code rather than underlying driver
default: F
atom_velo_rej_free_fully_randomize=[T | F]
If true, randomize velocities completely rather than just perturbing.
default: F
atom_velo_rej_free_perturb_angle=float
Max angle in radians for random rotations.
default: 0.3
MC_atom_velo_step_size=float
default: 50.0
MC_atom_velo_step_size_max=float
default: 10000.0
MC_atom_velo_walk_rej_free=[T | F]
default: T. If true, use rejection free algorithm for MC_atom_walk
MC_cell_P=float
Pressure value to be used. The unit of pressure depends on both the energy calculator and on the potential model used. Note that ASE uses
eV as energy and Angstrom as distance units everywhere, thus this case the pressure in the input have to be eV/Angstrom^3 (in case of using LAMMPS
the lammpslib module will convert the units for lammps to whatever units are set by the potential type)
default: 0.0
MC_cell_flat_V_prior=[T | F]
Flat prior for V (use with MC_cell_P=0 and cell moves, requires reweighting configurations when analyzing)
POORLY TESTED, DO NOT TRUST (YET).
default: F
MC_cell_volume_per_atom_step_size=float
Initial volume stepsize for volume change.
default: 5% of the maximum allowed volume
MC_cell_volume_per_atom_step_size_max=float
Maximum allowed volume step size.
default: 50% of the maximum allowed volume
MC_cell_volume_per_atom_prob=float
default: 1.0
MC_cell_stretch_step_size=float
default: 0.1
MC_cell_stretch_step_size_max=float
default: 1.0
MC_cell_stretch_prob=float
default: 1.0
MC_cell_shear_step_size=float
default: 0.1, in units of (max_volume_per_atom * N_atoms)^(1/3)
MC_cell_shear_step_size_max=float
default: 1.0, in units of (max_volume_per_atom * N_atoms)^(1/3)
MC_cell_shear_prob=float
default: 1.0
MC_cell_min_aspect_ratio=float
Smallest allowed distance between parallel faces for cell normalised to unit volume. A higher value of MC_cell_min_aspect_ratio restricts the system to more cube-like cell shapes, while a low value allows the system to become essentially flat. In case of 64 atoms the use of MC_cell_min_aspect_ratio < 0.65 does effect the melting transition.
default: 0.8
cell_shape_equil_steps=int
default: 1000
full_auto_step_sizes=[T | F]
If true (T), automatically calibrate all sizes by performing additional short explorations, including at the start of run. If false (F), use initial input step sizes and make small adjustments to these during the run.
default: T
monitor_step_interval_times_fraction_killed=float
Divided by n_cull/n_walkers to get actual monitoring interval in iterations, negative for only using last iteration, 0 for no monitoring
default: 1
adjust_step_interval_times_fraction_killed=float
Divided by n_cull/n_walkers to get actual step adjustment interval in iterations, negative for only using last iteration, 0 for no adjust.
default: 1
MC_adjust_step_factor=float
default: 1.1
MC_adjust_min_rate=float
default: 0.25
MC_adjust_max_rate=float
default: 0.75
GMC_adjust_min_rate=float
default: 0.25
GMC_adjust_max_rate=float
default: 0.75
GMC_dir_perturb_angle=float
default: -1.0
GMC_dir_perturb_angle_during=float
default: 0.0
MD_adjust_step_factor=float
default: 1.1
MD_adjust_min_rate=float
default: 0.5
MD_adjust_max_rate=float
default: 0.95
ASE_calc_module=str
MANDATORY if energy_calculator=ASE
FORTRAN_model=str
MANDATORY if energy_calculator=fortran
FORTRAN_model_params=str
parameters (optional) for fortran model
LAMMPS_fix_gmc=[T | F]
default: F
LAMMPS_init_cmds=str
MANDATORY if energy_calculator=lammps
LAMMPS_name=str
‘’, arch name for lammps shared object file
LAMMPS_serial=[T | F]
default True, lammps library is serial so do not pass COMM_SELF as a communicator
LAMMPS_header=str
lammpslib.py value default, override lammpslib.py header commands for energy_calculator=lammps
LAMMPS_header_extra=str
‘’, extra lammpslib.py header commands for energy_calculator=lammps
LAMMPS_atom_types=str
MANDATORY if energy_calculator=lammps
atomic_symbol1 lammps_type1 [, atomic_symbol2 lammps_type2, …]
mapping between atom species and lammps potential types
config_file_format=str
File format in which configurations are printed, e.g. for trajectory and snapshot files.
default: extxyz
rng=( numpy | internal | rngstream )
Random number generator.
default: numpy
profile=rank_to_profile
default: -1
2D=[ T | F ]
Perform 2D simulation. Some functionality may be limited with this option!
The 2D area is in the xy plane, the z axis stays constant during the simulation (set its value using the keyword Z_cell_axis).
The maximum allowed volume is still defined as volume in this case!
If constant pressure is set, the p*V term is now p*A*Z_cell_axis, thus set the MC_cell_P parameter multiplied by 1/Z_cell_axis.
default: F
Z_cell_axis=float
Only used if 2D=T. Value of the Z cell axis, perpendicular to the area in case of a 2D simulation.
This stays constant during the simulation.
default: 10.0
debug=int
Verbosity level used in the output file. The larger its value the more info is printed.
default: 0
snapshot_interval=int
Iteration interval at which a snapshot is created: every process prints out its current walkers in extended xyz format. If it is set <=0, no snapshots will be printed except the final positions at the end of the nested sampling run. Note that when new snapshots are printed, the previous set is deleted. The snapshot files are convenient source to see how the sampling progresses, but these are also the basis to restart a sampling! When using restart, the walkers will be read from these files.
default: 10000
snapshot_time=int
Max time between snapshots in seconds
default: 3600
snapshot_per_parallel_task=[ T | F ]
Save a separate snapshot file for each parallel task. Faster I/O (in parallel), but less convenient in some cases.
default: T
snapshot_clean=[ T | F ]
If true, delete previous iteration snapshot files
default: T
random_initialise_pos=[ T | F ]
If true, randomize the initial positions
default: T
random_initialise_cell=[ T | F ]
If true, randomize the initial cell (currently by random walk)
default: T
LAMMPS_molecular_info=[ T | F ]
If true, create lammps bonds and other molecular MM features from initial atoms config (e.g. can be read from a file)
default: T
initial_walk_N_walks=int
number of initial random walks to apply to all walkers
default: ‘’
initial_walk_adjust_interval=int
in initial walks, interval between walks for adjusting step size
default: ‘’
initial_walk_Emax_offset_per_atom=float
offset (per atom) to increase Emax during initial random walk applied to all walkers
default: 1.0
initial_walk_only=[T | F]
do initial walk only, then quit
default: F
traj_interval=int
Iteration interval at which the currently culled configuration(s) is/are printed to the trajectory output, in the set format. If it is set <=0, no trajectory files will be printed at all. Useful option for larger runs as the trajectory files can become huge.
default: 100
delta_random_seed=int
Random number seed to be used in the run. If smaller than 0, a seed from /dev/urandom is used.
default: -1
no_extra_walks_at_all=[ T | F ]
default: F
track_configs=[ T | F ]
Track configrations across all walks/clones.
default: F
track_configs_write=[ T | F ]
Write tracked configrations to a file (if false, tracking info will still be in snapshot and traj files)
default: F
ns_run_analyzers=string
Analyzers to apply during run. String consists of semicolon separated pairs of module name and intervals. Module names correspond to analysis modules in NS_PATH/ns_run_analyzers (see there for examples) or elsewhere in PYTHONPATH
Positive interval refers to NS loop, negative to initial walks
default:’’
min_nn_dis=float
Optional input to add additional rejection criteria when initially generating walkers. If any nearest neighbour distances are less than this length, given in Angstroms, the walker is rejected.
default: 0.0
calc_nn_dis=[ T | F ]
While you can set the min_nn_dis to add an additional rejection criteria to the initial walker generation, you can use this keyword to keep the rejection criteria on throughout the sampling. This does increase the calculation time of a run and scales exponentially with the number of atoms.
default: F
ns_run.velo_rv_mag(n)[source]
ns_run.velo_unit_rv(n)[source]
ns_run.walk_single_walker(at, movement_args, Emax, KEmax)[source]

Do random walk on a single atoms object.

ns_run.zero_stats(d, movement_args)[source]