WorkFlow for Automated Cluster Expansion Regression#

Modulated automation of cluster expansion model fitting based on atomate2 and Jobflow

test codacy_grade codacy_coverage precommit pypi_version static_badge

WFacer (“Wall”Facer) is a light-weight package based on smol to automate the fitting of lattice models in disordered crystalline solids using cluster expansion method. Beyond metallic alloys, WFacer is also designed to handle ionic systems through enabling decorators in WFacer.species_decorators.charge and the smol.cofe.extern.ewald.EwaldTerm.

Powered by Atomate2, Jobflow and Fireworks, WFacer is able to fully automate the cluster expansion building process on super-computing clusters, and can easily interface with MongoDB data storage in the Materials Project style.

Functionality#

WFacer currently offers the following functionalities:

  • Preprocess setup to a cluster expansion workflow as dictionary.

  • Enumerating and choosing the least aliasing super-cell matrices with given number of sites; enumerating charge balanced compositions in super-cells; Enumerating and selecting low-energy, non-duplicated structures into the training set at the beginning of each iteration.

  • Computing enumerated structures using Atomate2 VASP interfaces.

  • Extracting and saving relaxed structures information and energy in Atomate2 schemas.

  • Decorating structures. Currently, supports charge decoration from fixed labels, from Pymatgen guesses, or from a gaussian optimization process based on partitioning site magnetic moments.

  • Fitting effective cluster interactions (ECIs) from structures and energies with sparse linear regularization methods and model selection methods provided by sparse-lm, except for overlapped group Lasso regularization.

  • Checking convergence of cluster expansion model using the minimum energy convergence per composition, the cross validation error, and the difference of ECIs (if needed).

  • Creating an atomate2 style workflow to be executed locally or with Fireworks.

Installation#

  • From pypi: pip install WFacer

  • From source: git clone the repository. The latest tag in the main branch is the stable version of the code. The main branch has the latest tested features, but may have more lingering bugs. From the top level directory, do pip install -r requirements.txt, then pip install . If you wish to use Fireworks as the calculation manager, do pip install -r requirements-optional.txt as well.

Post-installation configuration#

Specific configurations are required before you can properly use WFacer.

  • Fireworks job management is highly recommended but not required. To use job management with Fireworks and Atomate2, configuring Fireworks and Atomate2 with your MongoDB storage is necessary. Users are advised to follow the guidance in Atomate2 and Atomate installation guides, and run a simple test workflow to see if it is able to run on your queue.

    Instead of writing in my_qadapter.yaml as

    rlaunch -c <<INSTALL_DIR>>/config rapidfire

    we suggest using:

    rlaunch -c <<INSTALL_DIR>>/config singleshot

    instead, because by using singleshot within rlaunch, a task in the submission queue will be terminated once a structure is finished instead of trying to fetch another structure from the launchpad. This can be used in combination with:

    qlaunch rapidfire -m <number of tasks to keep in queue>

    to guarantee that each structure is able to use up the maximum wall-time in its computation.

  • A mixed integer programming (MIP) solver would be necessary when a MIQP based regularization method is used. A list of available MIP solvers can be found in cvxpy documentations. Commercial solvers such as Gurobi and CPLEX are typically pre-compiled but require specific licenses to run on a super-computing system. For open-source solvers, the users are recommended to install SCIP in a dedicated conda environment following the installation instructions in PySCIPOpt.

Examples#

See Examples for some typical use cases.

License#

WFacer is distributed openly under a modified 3-clause BSD licence.

Workflows For Automated Cluster Expansion Regression (WFACER) Copyright (c) 2023,
The Regents of the University of California, through Lawrence Berkeley National
Laboratory (subject to receipt of any required approvals from the U.S.
Dept. of Energy) and the University of California, Berkeley. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

(1) Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

(2) Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

(3) Neither the name of the University of California, Lawrence Berkeley
National Laboratory, U.S. Dept. of Energy, University of California,
Berkeley nor the names of its contributors may be used to endorse or
promote products derived from this software without specific prior written
permission.


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

You are under no obligation whatsoever to provide any bug fixes, patches,
or upgrades to the features, functionality or performance of the source
code ("Enhancements") to anyone; however, if you choose to make your
Enhancements available either publicly, or directly to Lawrence Berkeley
National Laboratory, without imposing a separate written license agreement
for such Enhancements, then you hereby grant the following license: a
non-exclusive, royalty-free perpetual license to install, use, modify,
prepare derivative works, incorporate into other computer software,
distribute, and sublicense such enhancements or derivative works thereof,
in binary and source code form.