Package: pyace-lite
pyacepyaceis the python implementation of Atomic Cluster Expansion.
It provides the basis functionality for analysis, potentials conversion and fitting.
!!! THIS IS LIMITED FUNCTIONALITY VERSION OFpyace!!!Please, contact us by emailyury.lysogorskiy@rub.deif you want to have fully-functional versionInstallationpip install pyace-lite(optional) Installation oftensorpotentialIf you want to useTensorFlowimplementation of atomic cluster expansion
(made byDr. Anton Bochkarev), then contact us by email.(!) Known issuesIf you will encountersegmentation faulterrors,  then try to upgrade thenumpypackage with the command:pip install --upgrade numpy --forceDirectory structurelib/: contains the extra libraries forpyacesrc/pyace/: bindingsUtilitiesPotential conversionThere aretwobasic formats ACE potentials:B-basis setin YAML format, i.e. 'Al.pbe.yaml'. This is an internal developerscompleteformatCtilde-basis setin plain text format, i.e. 'Al.pbe.ace'. This format isirreversiblyconverted fromB-basis setfor
public potentials distribution and is used by LAMMPS.To convert potential you can use following utilities, that are installed together withpyacepackage into you executable paths:YAMLtoace:pace_yaml2ace. Usage:pace_yaml2ace [-h] [-o OUTPUT] inputPacemakerpacemakeris an utility for fitting the atomic cluster expansion potential. Usage:pacemaker [-h] [-o OUTPUT] [-p POTENTIAL] [-ip INITIAL_POTENTIAL]
                 [-b BACKEND] [-d DATA] [--query-data] [--prepare-data]
                 [-l LOG]
                 input

Fitting utility for atomic cluster expansion potentials

positional arguments:
  input                 input YAML file

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        output B-basis YAML file name, default:
                        output_potential.yaml
  -p POTENTIAL, --potential POTENTIAL
                        input potential YAML file name, will override input
                        file 'potential' section
  -ip INITIAL_POTENTIAL, --initial-potential INITIAL_POTENTIAL
                        initial potential YAML file name, will override input
                        file 'potential::initial_potential' section
  -b BACKEND, --backend BACKEND
                        backend evaluator, will override section
                        'backend::evaluator' from input file
  -d DATA, --data DATA  data file, will override section 'YAML:fit:filename'
                        from input file
  --query-data          query the training data from database, prepare and
                        save them
  --prepare-data        prepare and save training data only
  -l LOG, --log LOG     log filename (default log.txt)The required settings are provided by input YAML file. The main sections1. Cutoff and  (optional) metadataGlobal cutoff for the fitting is setup as:cutoff:10.0Metadata (optional)This is arbitrary key (string)-value (string) pairs that would be added to the potential YAML file:metadata:info:some infocomment:some commentpurpose:some purposeMoreover,starttimeanduserfields would be added automatically2.Dataset specification sectionFitting dataset could be queried automatically fromstructdb(if correspondingstructdbormpackage is installed and
connection to database is configured, seestructdb.inifile in home folder). Alternatively, dataset could be saved into
file as a pickledpandasdataframe with special names for columns: #TODO: add columns namesExample:data:# dataset specification section# data configuration sectionconfig:element:Al# element namecalculator:FHI-aims/PBE/tight# calculator type from `structdb`# ref_energy: -1.234           # single atom reference energy# if not specified, then it will be queried from database# seed: 42                       # random seed for shuffling the data# query_limit: 1000              # limiting number of entries to query from `structdb`# ignored if reading from cache# parallel: 3                    # number of parallel workers to preprocess the data, `pandarallel` package required# if not specified, serial mode will be used# cache_ref_df: True             # whether to store the queried or modified dataset into file, default - True# filename: some.pckl.gzip       # force to read reference pickled dataframe from given file# ignore_weights: False          # whether to ignore energy and force weighting columns in dataframe# datapath: ../data              # path to folder with cache files with pickled dataframesAlternatively, instead ofdata::configsection, one can specify just the cache file
with pickled dataframe asdata::filename:data:filename:small_df_tf_atoms.pckldatapath:../tests/Example of creating thesubselection of fitting dataframeand saving it is given innotebooks/data_preprocess.ipynbExample of generatingcustom energy/forces weightsis given innotebooks/data_custom_weights.ipynbQuerying dataYou can just query and preprocess data, without running potential fitting.
Here is the minimalistic input YAML:# input.yaml filecutoff:10.0# use larger cutoff to have excess neighbour listdata:# dataset specification sectionconfig:element:Al# element namecalculator:FHI-aims/PBE/tight# calculator type from `structdb`seed:42parallel:3# parallel data processing. WARNING! higher memory usage is possibledatapath:../data# path to the directory with cache files# query_limit: 100               # number of entries to queryThen executepacemaker --query-data input.yamlto query and build the dataset withpyaceneighbour lists.
For buildingbothpyaceandtensorpotneighbour lists usepacemaker --query-data input.yaml -b tensorpotPreparing the data / constructing neighbourlistsYou can use existing.pckl.gzipdataset and generate all necessary columns for that, including neighbourlists
Here is the minimalistic input YAML:# input.yaml filecutoff:10.data:filename:my_dataset.pckl.gzipbackend:evaluator:tensorpot# pyace, tensorpotThen executepacemaker --prepare-data input.yamlGeneration of themy_dataset.pckl.gzipfrom, for example,pyironis shown innotebooks/convert-pyiron-to-pacemaker.ipynb3. Interatomic potential (or B-basis) configurationOne could define the initial interatomic potential configuration as:potential:deltaSplineBins:0.001element:Alfs_parameters:[1,1,1,0.5]npot:FinnisSinclairNameOfCutoffFunction:cosrankmax:3nradmax:[4,3,3]# per-rank values of nradmaxlmax:[0,1,1]# per-rank values of lmax,  lmax=0 for first rank always!ndensity:2rcut:8.7dcut:0.01radparameters:[5.25]radbase:ChebExpCos##hard-core repulsion (optional)# core-repulsion: [500, 10]# rho_core_cut: 50# drho_core_cut: 20# basisdf:  /some/path/to/pyace_bbasisfunc_df.pckl      # path to the dataframe with "white list" of basis functions to use in fit# initial_potential: whatever.yaml                      # in "ladder" fitting scheme, potential from with to start fitIf you want to continue fitting of the existing potential inpotential.yamlfile, then specifypotential:potential yamlAlternatively, one could usepacemaker ... -p potential.yamloption4. Fitting settingsExample offitsection is:fit:loss:{kappa:0,L1_coeffs:0,L2_coeffs:0,w1_coeffs:0,w2_coeffs:0,w0_rad:0,w1_rad:0,w2_rad:0}weighting:type:EnergyBasedWeightingPolicynfit:10000cutoff:10DElow:1.0DEup:10.0DE:1.0DF:1.0wlow:0.75seed:42optimizer:BFGS# L-BFGS-B # Nelder-Meadmaxiter:1000# fit_cycles: 2               # (optional) number of consequentive runs of fitting algorithm,# that helps convergence# noise_relative_sigma: 1e-2   # applying Gaussian noise with specified relative sigma/mean ratio to all potential optimizable coefficients# noise_absolute_sigma: 1e-3   # applying Gaussian noise with specified absolute sigma to all potential optimizable coefficients# ladder_step: [10, 0.02]     # Possible values:#  - integer >= 1 - number of basis functions to add in ladder scheme,#  - float between 0 and 1 - relative ladder step size wrt. current basis step#  - list of both above values - select maximum between two possibilities on each iteration# see. Ladder scheme fitting for more info# ladder_type: body_order     # default# Possible values:# body_order  -  new basis functions are added according to the body-order, i.e., a function with higher body-order#                will not be added until the list of functions of the previous body-order is exhausted# power_order -  the order of adding new basis functions is defined by the "power rank" p of a function.#                p = len(ns) + sum(ns) + sum(ls). Functions with the smallest p are added firstIf not specified, thenuniform weightandenergy-onlyfit (kappa=0),fit_cycles=1,noise_relative_sigma= 0 settings will be used.5. Backend specificationbackend:evaluator:pyace# pyace, tensorpot## for `pyace` evaluator, following options are available:# parallel_mode: process    # process, serial  - parallelization mode for `pyace` evaluator# n_workers: 4              # number of parallel workers for `process` parallelization mode## for `tensorpot` evaluator, following options are available:# batch_size: 10            # batch size for loss function evaluation, default is 10# display_step: 20          # frequency of detailed metric calculation and printingAlternatively, backend could be selected aspacemaker ... -b tensorpotLadder scheme fittingIn a ladder scheme potential fitting happens by adding new portion of basis functions step-by-step,
to form a "ladder" frominitial potentialtofinal potential. Following settings should be added to
the input YAML file:Specifyfinal potentialshape by providingpotentialsection:potential:deltaSplineBins:0.001element:Alfs_parameters:[1,1,1,0.5]npot:FinnisSinclairNameOfCutoffFunction:cosrankmax:3nradmax:[4,1,1]lmax:[0,1,1]ndensity:2rcut:8.7dcut:0.01radparameters:[5.25]radbase:ChebExpCosSpecifyinitial or intermediate potentialby providinginitial_potentialoption inpotentialsection:potential:...initial_potential:some_start_or_interim_potential.yaml# potential to start fit fromIfinitial or intermediate potentialis not specified, then fit will start from empty potential.
Alternatively, you can specifyinitial or intermediate potentialby command-line optionpacemaker ... -ip some_start_or_interim_potential.yamlSpecifyladder_stepinfitsection:fit:...ladder_step:[10,0.02]# Possible values:#  - integer >= 1 - number of basis functions to add in ladder scheme,#  - float between 0 and 1 - relative ladder step size wrt. current basis step#  - list of both above values - select maximum between two possibilities on each iteration