casmcode/casm-base repository overview

⁠CASM: A Clusters Approach to Statistical Mechanics

This repository contains the base docker image for CASM.

CASM (https://github.com/prisms-center/CASMcode)⁠ is an open source software package designed to perform first-principles statistical mechanical studies of multi-component crystalline solids. CASM interfaces with first-principles electronic structure codes, automates the construction and parameterization of effective Hamiltonians and subsequently builds highly optimized (kinetic) Monte Carlo codes to predict finite-temperature thermodynamic and kinetic properties. CASM uses group theoretic techniques that take full advantage of crystal symmetry in order to rigorously construct effective Hamiltonians for almost arbitrary degrees of freedom in crystalline solids. This includes cluster expansions for configurational disorder in multi-component solids and lattice-dynamical effective Hamiltonians for vibrational degrees of freedom involved in structural phase transitions.

To use this image, first install docker with the instructions found here⁠. A brief introduction to docker and its usage may be found at this link⁠.

⁠Running CASM with docker

The casmcode/casm-base⁠ image contains a compiled version of the CASM program. After installing docker on your computer, you can obtain this image by running:

docker pull casmcode/casm-base

The casm image is now installed on your computer and can be invoked by using:

docker run --rm -it -v <data_folder>:/root/ casmcode/casm-base bash

• docker run --rm runs a temporary container that is removed after you are done using it
• -it allows you to access the container through your terminal
• -v shares the data you have in <data_folder> with the /root/ folder of your docker container. Remember to replace <data_folder> with a real location on your computer or you are likely to see several errors. The folder is mounted as volume on to the docker container and any changes you make to it will persist on your computer.
• casmcode/casm-base is the name of the image that you are using to build the container
• bash is the command that is invoked once the container is loaded.

Once you are within the docker container, you can run the code by invoking casm at the command line. If everything is working right you should see output that looks like:

root@461cdba0ce5a:~# casm
-- casm usage -- 
casm [--version] <command> [options] [args]
available commands:
 bset
 composition
 enum
 files
 format
 help
 import
 info
 init
 monte
 query
 ref
 rm
 run
 select
 settings
 status
 super
 sym
 update
 version
 view
For help using a command: 'casm <command> --help'
For step by step help use: 'casm status -n'

If you would like to customize your bash prompt, add a .bashrc file containing all the customization to your <data_folder>. When you mount it into the /root/ folder, it should automatically load the bashrc file.

⁠Important notes for running CASM

To compile the clexulator file through the casm bset -u command you will need to enable the following settings within casm. We recommend you run the following commands before invoking casm bset -u:

casm settings --set-cxx clang++
casm settings --set-casm-prefix $CASM_INSTALLDIR

⁠Utilizing the python libraries

The full stack of CASM software may be found in the casmcode/casm⁠ image. This includes the programs compiled within the casm-base image and the python library found at CASMpython⁠.

The programs installed in this image include the casm-learn package that helps fit cluster expansions and the casm-calc package that helps automate the running of electronic structure calculations on HPC clusters. Currently, the portion of casm-calc that submits jobs to run via a HPC queue (casm calc --submit) cannot work from within a Docker image. Other casm-calc functionality to generate input files, run calculations and collect results will still work.

⁠Singularity

Most HPC clusters do not allow the use of docker images. An alternative to using this precompiled docker image is singularity⁠. If your computing system supports it, you can easily setup a singularity image by running :

singularity pull docker://casmcode/casm-base

A detailed introduction and instructions for working with singularity may be found on their website⁠

⁠Acknowledgements

The development of CASM was made possible with support from:

• The U.S. Department of Energy, Office of Basic Energy Sciences, Division of Materials Sciences and Engineering under Award #DE-SC0008637 that funds the PRedictive Integrated Structural Materials Science (PRISMS) Center at University of Michigan.

• The National Science Foundation under Awards DMR-1410242, DMR-1105672, DMR-1436154, and OAC-1642433.

⁠Contact:

Contact the developers at [email protected]⁠.

The CASM development team will periodically send email notifications regarding new releases, features, and bug fixes to the CASM users notification list. To join the list send an email to [email protected]⁠ or visit https://lists.engr.ucsb.edu/mailman/listinfo/casm-users⁠ to sign up.

⁠License

GNU Lesser General Public License (LGPL). Please see the file LICENSE for details.