lerandc/construction_zone

Modules for generating nanoscale+ atomic scenes, primarily using pymatgen as generators with S/TEM image simulation in mind

Construction Zone

Modules for generating nanoscale+ atomic scenes, primarily using pymatgen as generators with S/TEM image simulation in mind.

Full documentation can be found here: https://construction-zone.readthedocs.io/.

If you use Construction Zone in your own work, we kindly ask that you cite the following: Rangel DaCosta, Luis, & Scott, Mary. (2021). Construction Zone (v2021.08.04). Zenodo. https://doi.org/10.5281/zenodo.5161161

Installation

Construction Zone can be easily installed with pip:

pip install czone

We strongly recommend utilizing an environment manager such as Anaconda, and installing Construction Zone into your environment of choice.

To install Construction Zone into a clean environment with Anaconda, you could do the following:

conda create -n environment_name python=3.7
conda activate environment_name
pip install czone

In this example, we manually set the target Python version to v3.7. Construction Zone has been tested only for Python 3.7 and above; earlier versions may work but are not supported.

Stable versions of Construction Zone will be passed onto PyPi. To use the current, development version of Construction Zone, you can set up the Python package in development mode. Again, we recommend doing so with an environment manager.

An example development installation could be achieved by the following:

conda create -n environment_name python=3.7
conda activate environment_name
git clone https://github.com/lerandc/construction_zone.git 
cd construction_zone
python setup.py --develop

Development mode installations import Python packages directly from the source every time. You could freely edit the source code yourself, or just use the installation to pull fresh code from the development branch by running git pull in the repository directory.

Manual Coverage Summaray (LRD, 2 Feb. 2024):

We have begun writing unit tests for Construction Zone. A partial coverage summary can be found below. For more a more detailed coverage summary, and information about testing priorities and a testing road map, please look towards the `tests' folder. Once unit tests for the core modules have been completed, CZ will be updated on relevant installatio channels. Minor to major refactoring can be expected in certain areas, but we will aim to have miminal breaking API changes, where possible.

(x = total, + = partial (direct), - = partial (indirect), blank = none)

[ ] Generator
| [ ] Amorphous Algorithms
| [ ] Generator Core

[x] Molecule

[ ] Prefab
| [ ] Prefab Core
| [ ] Wulff

[ ] Scene

[ ] Surface
| [ ] Adsorbate
| [ ] Alpha shapes

[-] Transform
| [ ] Post
| [ ] Strain
| [-] Transform Core

[ ] Util
| [ ] Measure
| [ ] Misc.

[ ] Viz

[+] Volume
| [+] Algebraic
| [ ] Volume Core
| [ ] Voxel

Acknowledgment

We acknowledge support for the development of Construction Zone from the Toyota Research Institute. This material is based upon work supported by the U.S. Department of Energy, Office of Science, Office of Advanced Scientific Computing Research, Department of Energy Computational Science Graduate Fellowship under Award Number DE-SC0021110.

This software was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor any agency thereof, nor any of their employees, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.

construction_zone's Issues

Probabilistic volume intersection

General description:
Conflict resolution in mutual volume intersection is decided probalistically

• Find use case first
• Perhaps make priority a typed property?

Get rid of loops in supply_atoms for crystalline generators

Probably a way to use vectorized operations to do a single large matrix multiply instead of loops

Surface chemistry transformations

General description:
Methods to select atoms on outer surfaces of objects and modify their chemistry

• Method to grab surface atoms
• Chemistry transformation class?

wrong code in tutorials

When I test it following the tutorial, I found something wrong.
The wrong code I found all in the picture below, which is in the last one code block in Defected FCC Nanoparticle on Carbon Substrate part. The parameter radius and small_sphere are not defined before, I think that sphere defined here is small_sphere.

Prefab structures

General description:
Submodule with various objects that are common constructions and can be called in sampleable fashion, e.g., decahedral particle with N twin defects

Fix import statements in tutorials

Object tags

Would be useful to tag created objects with some metadata, and at least have the ability to associate semantic metadata with objects so that they can be manipulated later.

For example, original miller indices of planes associated with prefab nanoparticles so that they can be expanded/truncated at will without having to backcalculate which plane is which from the plane normals

Surface-to-surface Alignment

Utility for aligning Volumes to eachother

Scope:

• Plane to plane
• Simplex to simplex
• Plane to simplex and vice versa

General Description:
given a target plane or simplex A in a stationary volume, and moving plane or simplex B in a different, moving volume, align A and B such that 1) plane normals are antiparallel 2) surfaces touch and 3) some minimal translation requirement is met

• Rotation of plane normals
• Translation minimization

Molecule/Surface Ligand support

General description:
Class for keeping molecules around and defining conflicts; ligand class to attach oriented molecules to surface of other objects

perhaps pymatgen has good support?
also check out https://pubs.acs.org/doi/10.1021/acs.jcim.0c01438

• Molecular volume class
• Conflict resolution strategies

perhaps for conflict resolution -> assume N atoms small, calculate distance to nearest volumes, check conflict resolution that way; translate atoms instead of deleting

Heterostructures

General description:
Prefab class for heterostructures; can sample N layers of each constituent layer and potentially strain

Reciprocal Lattice hook-ins

Multi-volume

General Description:
Super class to volumes that keeps logical objects stored together, so that transformations don't have to be applied to volumes that are logically grouped

5-17-21: basic implementation finished in b55d371

• Base class for volumes, multivolumes
• Method to loop through subvolumes and apply transformations
• Example notebook
• Testing (particularly of conflicting priorities)