ascii-phonons

Visualisation of crystal vibrations with Blender.

Visualisation is a powerful tool for the study of vibrations in the solid state. "Semi-automatic" animations have been generated for scientific publications, where they provide insight to spectroscopic observations.[1,2] (Images 1, 2.) In order to make this type of imagery more accessible, and add some visual interest to ajjackson's PhD thesis, a more convenient and automatic toolchain is desirable.

Please use the issue tracker for feature requests, bug reports and more general questions.

A presentation outlining some features and implementation details is available online.

Features

• There is a GUI and a command-line interface, for easy accessibility and scripting potential.
• Import atomic positions, unit cell and phonon modes from .ascii files
• Use open-source graphics package Blender to render images; the end-user is not required to interact with the Blender GUI unless they want to
• Create static or animated images showing the unit cell bounding box, atomic positions and eigenvectors
• Use ImageMagick to export .gif files for use in web browser
• Arbitrary supercells are defined by three counting numbers. The displayed bounding box may be shifted within this structure.
• Animated images include movements of atoms with the phase shift in different unit cells for off-Gamma phonons
• Arrows indicating eigenvectors do not include phase information
• The output has an attractive "cartoon-like" visual style with flat colours and outlines.
• Atom colours are assigned from a default or user config file. If undefined, a random colour is selected.
• Mass-weighting may optionally be added if this was not done in the .ascii file construction.

Development

The target for input files is the ASCII format used by v_sim, a useful program and currently one of the only tools available for visualising phonons. These files contain all the information needed to define a crystal sructure and its vibrations. It is presumed that these are generated by Phonopy from ab initio electronic structure calculations, and initially this code will only target the features used by Phonopy. Extension to the full ASCII format is of course welcome. Animation and rendering will be done in Blender. The preferred approach to Blender is to write an "add-on" which carries out importing duties.

Developing Blender add-ons can be a bit clunky as one is required to mess around with the GUI when testing changes, so there may be some hackery to get around this. Building Blender as a Python library would ease development considerably, but appears to be quite difficult to do on a Mac.

The target platforms are modern GNU/Linux distributions and Mac OS X. Operation under Windows is not actively being tested, but should be possible.

Setup

The simplest way to get up and running is

1. Install Blender (available in all good package managers).
2. Download the code:
   • either clone the repository with git clone git@github.com:ajjackson/ascii-phonons
   • or download the latest version as a zip file.

Requirements

• Some means of generating .ascii files. We like Phonopy.
• A recent version of Blender; development is currently with Blender 2.76 and later. At least version 2.70 is needed, which provides the wireframe modifier used to draw the bounding box. Note that the versions of Blender available in package managers such as apt-get are often quite dated. Installing the latest version for Linux is easy, however; just download the .tar.gz file, untar it and add the directory to your PATH.
• Imagemagick tools (specifically "convert" and "montage") are used for image conversion and tiling. This is available in most package managers and may even be pre-installed with your Unix-like operating system.
• The GUI uses Tkinter with the python image library. On Linux this is typically packaged as python-imaging-tk. Mac OSX and Windows Python distributions tend to include Tkinter, but it may be necessary to also install a PIL implementation such as Pillow.

Using ascii-phonons

For those who would prefer to avoid working through the Python API, a command-line wrapper scripts/ascii-phonons and a graphical user intergace scripts/ascii-phonons-gui are available. Call the script with

python blend_ascii.py -h

for information about the numerous command-line arguments, or take a look at the fancy online documentation.

If working on Mac OS X, you may need to specify the path to your Blender binary, which is tucked away in a .app package, using the -b flag. However, the script assumes you have Blender installed in a folder called "Blender" in the root Applications folder, and should find your binary in this case.

A typical call to the wrapper script would be something like:

ascii-phonons /path/to/my/phonons.ascii -m 5 --static --vectors -o pretty

which should write a static image pretty.png, illustrating mode 5 with arrows. To generate an animation, try

ascii-phonons /path/to/my/phonons.ascii -m 1 --gif -o pretty

which will use Imagemagick to generate pretty.gif.

Implementation details

The default atomic radii are the covalent radii from Cordero et al (2008). The eigenvectors are scaled by the square root of the relative atomic mass; the atomic mass data is from Coursey et al. (2015).

Acknowledgements

Work on this package began while ajjackon was a PhD student funded by EPSRC through the Center for Sustainable Chemical Technologies (grant no. EP/G03768X/1) at the University of Bath. Further work to fix bugs and improve the documentation and useability has taken place as a Research Assistant the same research group, while funded by the ERC (project 277757).

License

GNU GPL v3

Disclaimer

Use at your own risk. This project is not affiliated with Blender, Phonopy or v_sim.