BuildRecursiveTable

class BuildRecursiveTable : public feasst::Action

This class is experimental. The RecursiveTable is generated by comparing with the output of MayerSampling::training_file. This example assumes single-site isotropic interactions, in which case the training file simply contains a list of squared distances and energy.

To begin, an inner cutoff distance is obtained by finding the lowest distance at which the energy is less than the given parameter “hard_limit_u.” The outer cutoff is can be set manually or automatically generated.

A 1D RecursiveTable of given size is generated by linearly interpolating between the closest data points.

Then all of the data is evaluated against the following criteria in order to iteratively insert nested tables inside the elements of the first table,

\(r^2|\exp(-\beta U) - \exp(-\beta U_{table})|\),

where \(U\) is from the data points, \(U_{table}\) is linearly interpolated, and \(\beta\) is a given parameter which determines the relative emphasis on accurately fitting the highest energies. This functional form was inspired by the 3d integration of a Mayer funciton to include the \(r^2\) Jacobian term to appropriately weight larger distances. In addition, increased beta (low temperature) weighs the low energy configurations more. This iterative process continues until the criteria of all data points are less than the given “min_criteria.”

As currently implemented, the RecursiveTable has a maximum depth of one recursion. This means that “min_criteria” can be set too low and never achieved, at which point the user will be presented with an error. This happens if a data point inside of an element that has already had a RecursiveTable inserted is still above the “min_criteria.”

Parallel algorithm:

  1. In parallel, run Mayer-sampling simulations to generate training data

  2. In parallel, build base table for rh (if applicable, also rc and U)

    • aggregate of all training data is required because build automatically determines global cutoff and contact based on all data.

  3. In serial, combine tables into one base table.

  4. In parallel, read Mayer trainining file line by line to determine which base table elements are to be nested.

    • optionally, stop at certain max percentage?

    • optionally, sort nested by deviation from criteria

  5. In serial (post-process), union set of elements to be nested from each processor to avoid duplicates

  6. In parallel, build nested tables.

  7. In serial (post-process) combine into one nested table.

    • optionally, check that max deviation from criteria does not occur in a nested element, or else the criteria was too strict and may have resulted in inefficiently nesting too many.

Multiple script HPC example allows submission of many single core jobs by completing one stage at a time:

  • (before stages): MayerSampling (step 1, postprocess combine data)

  • ”base” stage: (step 2, postprocess step 3)

  • ”train” stage: (step 4, postprocess step 5)

  • ”build” stage: (step 6, postprocess step 7)

    • optionally, Prepare during Mayer to avoid large data files, but this requires deciding table parameters. Changing parameters would require rerunning the MayerSampling portion.

Arguments

  • stage: if all (default), run all stages with limited-efficiency OMP parallelization. If base, train, build_contact, build_cutoff, build_energy, only complete the stage described above (enables processor- based parallelization). If base, automatically sets assume_all_unique to true and min_criteria to NEAR_INFINITY. If build*, automatically sets assume_all_unique to true.

  • mayer_training_file: input file, output by MayerSampling::training_file.

  • cutoff: cutoff distance. If -1, find automatically (default: -1).

  • output_file: write RecursiveTablePotential checkpoint file.

  • verbose_file: output file for more fitting information (default: empty).

  • extra_verbose: If true, output even more more (default: false).

  • hard_limit_u: determines the inner cutoff distance (default: 100).

  • num_orientations_per_pi: angular size of each of the RecursiveTable s (default: 5).

  • beta: parameter which weights low energy configurations (default: 1). Only affects energy tables, so not required for contact_only (see below).

  • contact_only: If true, only consider hard contact (default: false).

  • energy_only: If true, only consider energy (default: false).

  • input_recursive_table: optionally, if energy_only, input existing contact and cutoff by providing the file name of the RecursiveTable VisitModelInnerTable.

  • num_z: the number of distances for each of the RecursiveTable s (default: 5). Only affects energy tables, so not required for contact_only (see below).

  • min_criteria: iterative target minimum criteria (default: 0.03).

  • min_criteria_energy: iterative target minimum criteria for energy. (default: 0). If <= 0, set to min_criteria above.

  • assume_all_unique: if true, do not search for uniqueness (default: false).

  • num_processors: number of processors to parallelize (default: 1).

  • processor: index of current processor [0, num_processors-1] (default: 0).

  • base_table_file: optional file name output from BuildBaseTable.

  • trained_file: optionally, if provided with base_table_file, generate the recursive tables without requiring criteria/beta/hard_limit_u, etc.