Upload 877 files

.gitattributes

@@ -33,3 +33,72 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.10_Differential_Displacement_Maps_20_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.4._Volterra_dislocation_solutions_28_1.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.4._Volterra_dislocation_solutions_30_1.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.6._Dislocation_analysis_tools_14_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.6._Dislocation_analysis_tools_34_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.8._Strain_class_24_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.8._Strain_class_24_1.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.8._Strain_class_24_2.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.9._Dislocation_configurations_generator_45_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.9._Dislocation_configurations_generator_46_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.9._Dislocation_configurations_generator_67_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/_images/tutorial_4.9._Dislocation_configurations_generator_68_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.Box.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.cluster.BondAngleMap.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.DifferentialDisplacement.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.Dislocation.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.FreeSurface.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.GammaSurface.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.IsotropicVolterraDislocation.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.SDVPN.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.StackingFault.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.Stroh.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.defect.VolterraDislocation.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.ElasticConstants.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.library.Database.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.mep.BasePath.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.plot.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.region.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.System.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.tools.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/atomman.unitconvert.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.10_Differential_Displacement_Maps_20_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.4._Volterra_dislocation_solutions_28_1.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.4._Volterra_dislocation_solutions_30_1.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.6._Dislocation_analysis_tools_14_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.6._Dislocation_analysis_tools_34_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.8._Strain_class_24_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.8._Strain_class_24_1.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.8._Strain_class_24_2.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.9._Dislocation_configurations_generator_45_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.9._Dislocation_configurations_generator_46_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.9._Dislocation_configurations_generator_67_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/nbsphinx/tutorial_4.9._Dislocation_configurations_generator_68_0.png filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/0._Unit_conversions.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1._Defining_atomic_systems.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.1._Box_class.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.2._Atoms_class.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.3._System_class.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.4.1._system_model_conversions.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.4.12._DFT_reference_crystal_loading.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.4.5._LAMMPS_data_file_conversions.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.5._Settings_and_databases.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/1.5._Settings_and_Library_classes.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/2._LAMMPS_functionality.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/2.1._Potential_class.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/3._Basic_support_and_analysis_tools.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/3.1._ElasticConstants_class.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/3.2._NeighborList_class.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.1._Point_defect_generation.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.2._Free_surface_generator.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.3._Stacking_fault_generator.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.4._Dislocation_solution_and_generator.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.4._Volterra_dislocation_solutions.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.5._Gamma_surface_plotting.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.6._Dislocation_analysis_tools.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.7._Semidiscrete_variational_Peierls-Nabarro_model.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.8._Strain_class.doctree filter=lfs diff=lfs merge=lfs -text
+atomman/source/doc/html/.doctrees/tutorial/4.9._Dislocation_configurations_generator.doctree filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.10
+
+RUN useradd -m -u 1000 user && python -m pip install --upgrade pip
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+ENV MCP_TRANSPORT=http
+ENV MCP_PORT=7860
+
+EXPOSE 7860
+
+CMD ["python", "atomman/mcp_output/start_mcp.py"]

README.md

@@ -1,10 +1,32 @@
 ---
-title: Atomman
-emoji: 🔥
-colorFrom: purple
-colorTo: yellow
+title: Atomman MCP
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
 sdk: docker
+sdk_version: "4.26.0"
+app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Atomman MCP Service
+
+Auto-generated MCP service for atomman.
+
+## Usage
+
+```
+https://None-atomman-mcp.hf.space/mcp
+```
+
+## Connect with Cursor
+
+```json
+{
+  "mcpServers": {
+    "atomman": {
+      "url": "https://None-atomman-mcp.hf.space/mcp"
+    }
+  }
+}
+```

app.py

@@ -0,0 +1,45 @@
+from fastapi import FastAPI
+import os
+import sys
+
+mcp_plugin_path = os.path.join(os.path.dirname(__file__), "atomman", "mcp_output", "mcp_plugin")
+sys.path.insert(0, mcp_plugin_path)
+
+app = FastAPI(
+    title="Atomman MCP Service",
+    description="Auto-generated MCP service for atomman",
+    version="1.0.0"
+)
+
+@app.get("/")
+def root():
+    return {
+        "service": "Atomman MCP Service",
+        "version": "1.0.0",
+        "status": "running",
+        "transport": os.environ.get("MCP_TRANSPORT", "http")
+    }
+
+@app.get("/health")
+def health_check():
+    return {"status": "healthy", "service": "atomman MCP"}
+
+@app.get("/tools")
+def list_tools():
+    try:
+        from mcp_service import create_app
+        mcp_app = create_app()
+        tools = []
+        for tool_name, tool_func in mcp_app.tools.items():
+            tools.append({
+                "name": tool_name,
+                "description": tool_func.__doc__ or "No description available"
+            })
+        return {"tools": tools}
+    except Exception as e:
+        return {"error": f"Failed to load tools: {str(e)}"}
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run(app, host="0.0.0.0", port=port)

atomman/mcp_output/README_MCP.md

@@ -0,0 +1,77 @@
+# Atomman: Atomistic Manipulation Toolkit
+
+## Project Introduction
+
+Atomman is a comprehensive toolkit designed for atomistic manipulation and simulation. It provides a robust set of tools for handling atomic structures, simulating dislocations, and interfacing with LAMMPS for potential evaluations. The toolkit is particularly useful for researchers and developers working in materials science and computational physics, offering functionalities such as atomic position management, simulation box transformations, and plotting capabilities using Plotly.
+
+## Installation Method
+
+To install Atomman, ensure you have Python installed along with the following dependencies:
+
+- Required: numpy, scipy, matplotlib
+- Optional: plotly, ase
+
+You can install Atomman and its dependencies using pip:
+
+```
+pip install atomman
+```
+
+## Quick Start
+
+Here's a quick example to get you started with Atomman:
+
+1. **Handling Atomic Positions:**
+
+   Use the `Atoms` class to manage atomic positions and velocities.
+
+   ```
+   from atomman import Atoms
+
+   atoms = Atoms()
+   atoms.set_positions([[0, 0, 0], [1, 1, 1]])
+   positions = atoms.get_positions()
+   ```
+
+2. **Defining Simulation Box:**
+
+   Use the `Box` class to define and manipulate the simulation box dimensions.
+
+   ```
+   from atomman import Box
+
+   box = Box()
+   box.set_dimensions([10, 10, 10])
+   dimensions = box.get_dimensions()
+   ```
+
+3. **Plotting Structures:**
+
+   Plot atomic structures using Plotly.
+
+   ```
+   from atomman.plot import plotly
+
+   plotly.plot_structure(atoms)
+   ```
+
+## Available Tools and Endpoints List
+
+- **Atoms (source.atomman.core.Atoms):** Handles atomic positions and velocities.
+- **Box (source.atomman.core.Box):** Defines the simulation box dimensions and transformations.
+- **Dislocation (source.atomman.defect.Dislocation):** Models dislocations and calculates related properties.
+- **Potential (source.atomman.lammps.Potential):** Handles LAMMPS potential files and evaluations.
+- **Plotly (source.atomman.plot.plotly):** Provides plotting capabilities using Plotly.
+
+## Common Issues and Notes
+
+- Ensure all required dependencies are installed to avoid import errors.
+- Optional dependencies like Plotly and ASE enhance functionality but are not mandatory.
+- The toolkit's complexity and medium intrusiveness risk suggest careful integration into larger projects.
+- Performance may vary based on the size of the atomic systems being manipulated.
+
+## Reference Links or Documentation
+
+For more detailed documentation and examples, visit the [Atomman GitHub Repository](https://github.com/usnistgov/atomman).
+
+For further assistance, refer to the official documentation once the repository is indexed for code exploration and search functionality.

atomman/mcp_output/analysis.json

@@ -0,0 +1,871 @@
+{
+  "summary": {
+    "repository_url": "https://github.com/usnistgov/atomman",
+    "summary": "Imported via zip fallback, file count: 243",
+    "file_tree": {
+      "LICENSE.TXT": {
+        "size": 2752
+      },
+      "atomman/__init__.py": {
+        "size": 1351
+      },
+      "atomman/cluster/BondAngleMap.py": {
+        "size": 30506
+      },
+      "atomman/cluster/__init__.py": {
+        "size": 66
+      },
+      "atomman/core/Atoms.py": {
+        "size": 21541
+      },
+      "atomman/core/Box.py": {
+        "size": 38743
+      },
+      "atomman/core/ElasticConstants.py": {
+        "size": 39453
+      },
+      "atomman/core/ElasticConstants2.py": {
+        "size": 41525
+      },
+      "atomman/core/NeighborList.py": {
+        "size": 9154
+      },
+      "atomman/core/System.py": {
+        "size": 47719
+      },
+      "atomman/core/__init__.py": {
+        "size": 485
+      },
+      "atomman/core/displacement.py": {
+        "size": 1602
+      },
+      "atomman/defect/Boundary.py": {
+        "size": 34846
+      },
+      "atomman/defect/DifferentialDisplacement.py": {
+        "size": 34861
+      },
+      "atomman/defect/Dislocation/__init__.py": {
+        "size": 22706
+      },
+      "atomman/defect/Dislocation/_dipole.py": {
+        "size": 12786
+      },
+      "atomman/defect/Dislocation/_monopole.py": {
+        "size": 13693
+      },
+      "atomman/defect/Dislocation/_periodicarray.py": {
+        "size": 19228
+      },
+      "atomman/defect/FreeSurface.py": {
+        "size": 27413
+      },
+      "atomman/defect/GRIP.py": {
+        "size": 25781
+      },
+      "atomman/defect/GammaSurface.py": {
+        "size": 54638
+      },
+      "atomman/defect/GrainBoundary.py": {
+        "size": 10235
+      },
+      "atomman/defect/InterstitialSite.py": {
+        "size": 5663
+      },
+      "atomman/defect/IsotropicVolterraDislocation.py": {
+        "size": 10971
+      },
+      "atomman/defect/SDVPN.py": {
+        "size": 48201
+      },
+      "atomman/defect/StackingFault.py": {
+        "size": 30033
+      },
+      "atomman/defect/Stroh.py": {
+        "size": 11732
+      },
+      "atomman/defect/SurfaceEnergyEstimator.py": {
+        "size": 7009
+      },
+      "atomman/defect/Surface_energy_formula.py": {
+        "size": 3087
+      },
+      "atomman/defect/TiltGrainBoundaryHelper.py": {
+        "size": 20221
+      },
+      "atomman/defect/VolterraDislocation.py": {
+        "size": 15075
+      },
+      "atomman/defect/__init__.py": {
+        "size": 2157
+      },
+      "atomman/defect/differential_displacement.py": {
+        "size": 14804
+      },
+      "atomman/defect/dislocation_array.py": {
+        "size": 9874
+      },
+      "atomman/defect/dislocation_dipole_displacement.py": {
+        "size": 5391
+      },
+      "atomman/defect/dislocation_system_basis.py": {
+        "size": 8440
+      },
+      "atomman/defect/dislocation_system_transform.py": {
+        "size": 3052
+      },
+      "atomman/defect/disregistry.py": {
+        "size": 4501
+      },
+      "atomman/defect/free_surface_basis.py": {
+        "size": 10698
+      },
+      "atomman/defect/generator_tools.py": {
+        "size": 6322
+      },
+      "atomman/defect/nye_tensor.py": {
+        "size": 6895
+      },
+      "atomman/defect/nye_tensor_p.py": {
+        "size": 1883
+      },
+      "atomman/defect/pn_arctan_disldensity.py": {
+        "size": 4344
+      },
+      "atomman/defect/pn_arctan_disregistry.py": {
+        "size": 4171
+      },
+      "atomman/defect/point.py": {
+        "size": 16357
+      },
+      "atomman/defect/solve_volterra_dislocation.py": {
+        "size": 4283
+      },
+      "atomman/defect/surface_energy_estimate.py": {
+        "size": 3087
+      },
+      "atomman/dump/__init__.py": {
+        "size": 1727
+      },
+      "atomman/dump/ase_Atoms/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/ase_Atoms/dump.py": {
+        "size": 1963
+      },
+      "atomman/dump/atom_data/__init__.py": {
+        "size": 138
+      },
+      "atomman/dump/atom_data/atoms_prop_info.py": {
+        "size": 14356
+      },
+      "atomman/dump/atom_data/dump.py": {
+        "size": 9032
+      },
+      "atomman/dump/atom_data/velocities_prop_info.py": {
+        "size": 3205
+      },
+      "atomman/dump/atom_dump/__init__.py": {
+        "size": 87
+      },
+      "atomman/dump/atom_dump/dump.py": {
+        "size": 10881
+      },
+      "atomman/dump/atom_dump/process_prop_info.py": {
+        "size": 9444
+      },
+      "atomman/dump/conventional_to_primitive/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/conventional_to_primitive/dump.py": {
+        "size": 12698
+      },
+      "atomman/dump/freud/__init__.py": {
+        "size": 22
+      },
+      "atomman/dump/freud/dump.py": {
+        "size": 1260
+      },
+      "atomman/dump/lammps_commands/__init__.py": {
+        "size": 22
+      },
+      "atomman/dump/lammps_commands/dump.py": {
+        "size": 7907
+      },
+      "atomman/dump/neb_replica/__init__.py": {
+        "size": 22
+      },
+      "atomman/dump/neb_replica/dump.py": {
+        "size": 2841
+      },
+      "atomman/dump/pdb/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/pdb/dump.py": {
+        "size": 2620
+      },
+      "atomman/dump/phonopy_Atoms/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/phonopy_Atoms/dump.py": {
+        "size": 2125
+      },
+      "atomman/dump/poscar/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/poscar/dump.py": {
+        "size": 3703
+      },
+      "atomman/dump/primitive_cell/__init__.py": {
+        "size": 22
+      },
+      "atomman/dump/primitive_cell/dump.py": {
+        "size": 1659
+      },
+      "atomman/dump/primitive_to_conventional/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/primitive_to_conventional/dump.py": {
+        "size": 2247
+      },
+      "atomman/dump/pymatgen_Structure/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/pymatgen_Structure/dump.py": {
+        "size": 1644
+      },
+      "atomman/dump/spglib_cell/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/spglib_cell/dump.py": {
+        "size": 656
+      },
+      "atomman/dump/standardize_cell/__init__.py": {
+        "size": 39
+      },
+      "atomman/dump/standardize_cell/dump.py": {
+        "size": 2772
+      },
+      "atomman/dump/system_model/__init__.py": {
+        "size": 38
+      },
+      "atomman/dump/system_model/dump.py": {
+        "size": 3743
+      },
+      "atomman/dump/table/__init__.py": {
+        "size": 87
+      },
+      "atomman/dump/table/dump.py": {
+        "size": 5842
+      },
+      "atomman/dump/table/process_prop_info.py": {
+        "size": 5221
+      },
+      "atomman/lammps/Log.py": {
+        "size": 13229
+      },
+      "atomman/lammps/NEBLog.py": {
+        "size": 6561
+      },
+      "atomman/lammps/Potential.py": {
+        "size": 3109
+      },
+      "atomman/lammps/__init__.py": {
+        "size": 838
+      },
+      "atomman/lammps/checkversion.py": {
+        "size": 1432
+      },
+      "atomman/lammps/normalize.py": {
+        "size": 2578
+      },
+      "atomman/lammps/run.py": {
+        "size": 5882
+      },
+      "atomman/lammps/seed.py": {
+        "size": 1171
+      },
+      "atomman/lammps/style.py": {
+        "size": 7053
+      },
+      "atomman/library/Database/__init__.py": {
+        "size": 2692
+      },
+      "atomman/library/Database/_crystal_prototype.py": {
+        "size": 17337
+      },
+      "atomman/library/Database/_reference_crystal.py": {
+        "size": 28410
+      },
+      "atomman/library/Database/_relaxed_crystal.py": {
+        "size": 20326
+      },
+      "atomman/library/__init__.py": {
+        "size": 276
+      },
+      "atomman/library/load_lammps_potential.py": {
+        "size": 6362
+      },
+      "atomman/library/record/CrystalPrototype.py": {
+        "size": 3073
+      },
+      "atomman/library/record/Dislocation.py": {
+        "size": 4207
+      },
+      "atomman/library/record/FreeSurface.py": {
+        "size": 2794
+      },
+      "atomman/library/record/GrainBoundary.py": {
+        "size": 3887
+      },
+      "atomman/library/record/PointDefect.py": {
+        "size": 4179
+      },
+      "atomman/library/record/ReferenceCrystal.py": {
+        "size": 4020
+      },
+      "atomman/library/record/RelaxedCrystal.py": {
+        "size": 6735
+      },
+      "atomman/library/record/StackingFault.py": {
+        "size": 3601
+      },
+      "atomman/library/record/__init__.py": {
+        "size": 769
+      },
+      "atomman/library/value/MillerValue.py": {
+        "size": 4962
+      },
+      "atomman/library/value/SystemModelValue.py": {
+        "size": 2325
+      },
+      "atomman/library/value/UnitVectorValue.py": {
+        "size": 5304
+      },
+      "atomman/library/value/VectorValue.py": {
+        "size": 4768
+      },
+      "atomman/library/value/__init__.py": {
+        "size": 301
+      },
+      "atomman/library/xsd/__init__.py": {
+        "size": 0
+      },
+      "atomman/library/xsl/__init__.py": {
+        "size": 0
+      },
+      "atomman/load/__init__.py": {
+        "size": 1823
+      },
+      "atomman/load/ase_Atoms/__init__.py": {
+        "size": 38
+      },
+      "atomman/load/ase_Atoms/load.py": {
+        "size": 1527
+      },
+      "atomman/load/atom_data/__init__.py": {
+        "size": 138
+      },
+      "atomman/load/atom_data/atoms_prop_info.py": {
+        "size": 14351
+      },
+      "atomman/load/atom_data/load.py": {
+        "size": 13573
+      },
+      "atomman/load/atom_data/velocities_prop_info.py": {
+        "size": 3200
+      },
+      "atomman/load/atom_dump/__init__.py": {
+        "size": 87
+      },
+      "atomman/load/atom_dump/load.py": {
+        "size": 10106
+      },
+      "atomman/load/atom_dump/process_prop_info.py": {
+        "size": 9377
+      },
+      "atomman/load/cif/__init__.py": {
+        "size": 38
+      },
+      "atomman/load/cif/load.py": {
+        "size": 1887
+      },
+      "atomman/load/crystal/__init__.py": {
+        "size": 22
+      },
+      "atomman/load/crystal/load.py": {
+        "size": 6261
+      },
+      "atomman/load/dft_reference/__init__.py": {
+        "size": 22
+      },
+      "atomman/load/dft_reference/load.py": {
+        "size": 2914
+      },
+      "atomman/load/phonopy_Atoms/__init__.py": {
+        "size": 38
+      },
+      "atomman/load/phonopy_Atoms/load.py": {
+        "size": 1641
+      },
+      "atomman/load/poscar/__init__.py": {
+        "size": 38
+      },
+      "atomman/load/poscar/load.py": {
+        "size": 3020
+      },
+      "atomman/load/prototype/__init__.py": {
+        "size": 22
+      },
+      "atomman/load/prototype/load.py": {
+        "size": 9535
+      },
+      "atomman/load/pymatgen_Structure/__init__.py": {
+        "size": 38
+      },
+      "atomman/load/pymatgen_Structure/load.py": {
+        "size": 1532
+      },
+      "atomman/load/spglib_cell/__init__.py": {
+        "size": 38
+      },
+      "atomman/load/spglib_cell/load.py": {
+        "size": 989
+      },
+      "atomman/load/system_model/__init__.py": {
+        "size": 38
+      },
+      "atomman/load/system_model/load.py": {
+        "size": 6126
+      },
+      "atomman/load/table/__init__.py": {
+        "size": 87
+      },
+      "atomman/load/table/load.py": {
+        "size": 5102
+      },
+      "atomman/load/table/process_prop_info.py": {
+        "size": 5390
+      },
+      "atomman/mep/BasePath.py": {
+        "size": 12325
+      },
+      "atomman/mep/ISMPath.py": {
+        "size": 10487
+      },
+      "atomman/mep/__init__.py": {
+        "size": 2103
+      },
+      "atomman/mep/gradient/__init__.py": {
+        "size": 100
+      },
+      "atomman/mep/gradient/central_difference.py": {
+        "size": 1653
+      },
+      "atomman/mep/integrator/__init__.py": {
+        "size": 110
+      },
+      "atomman/mep/integrator/euler.py": {
+        "size": 859
+      },
+      "atomman/mep/integrator/rungekutta.py": {
+        "size": 1095
+      },
+      "atomman/plot/__init__.py": {
+        "size": 385
+      },
+      "atomman/plot/get_prop_values.py": {
+        "size": 2651
+      },
+      "atomman/plot/interpolate_contour.py": {
+        "size": 15813
+      },
+      "atomman/plot/nglview.py": {
+        "size": 3624
+      },
+      "atomman/plot/nglview_classes.py": {
+        "size": 2526
+      },
+      "atomman/plot/plotly.py": {
+        "size": 4126
+      },
+      "atomman/plot/py3Dmol.py": {
+        "size": 4139
+      },
+      "atomman/plot/values_to_hexcolors.py": {
+        "size": 1928
+      },
+      "atomman/region/Cylinder.py": {
+        "size": 4072
+      },
+      "atomman/region/Plane.py": {
+        "size": 5378
+      },
+      "atomman/region/PlaneSet.py": {
+        "size": 2124
+      },
+      "atomman/region/Shape.py": {
+        "size": 1681
+      },
+      "atomman/region/Sphere.py": {
+        "size": 2216
+      },
+      "atomman/region/__init__.py": {
+        "size": 220
+      },
+      "atomman/thermo/EinsteinSolid.py": {
+        "size": 3655
+      },
+      "atomman/thermo/IdealGas.py": {
+        "size": 1998
+      },
+      "atomman/thermo/RDF.py": {
+        "size": 7969
+      },
+      "atomman/thermo/UhlenbeckFordModel.py": {
+        "size": 75553
+      },
+      "atomman/thermo/__init__.py": {
+        "size": 143
+      },
+      "atomman/tools/__init__.py": {
+        "size": 1072
+      },
+      "atomman/tools/approx_rational.py": {
+        "size": 1278
+      },
+      "atomman/tools/axes_check.py": {
+        "size": 1234
+      },
+      "atomman/tools/boolean.py": {
+        "size": 915
+      },
+      "atomman/tools/compositionstr.py": {
+        "size": 1035
+      },
+      "atomman/tools/crystalsystem.py": {
+        "size": 8935
+      },
+      "atomman/tools/duplicated_allclose.py": {
+        "size": 6754
+      },
+      "atomman/tools/duplicates_allclose.py": {
+        "size": 6072
+      },
+      "atomman/tools/filltemplate.py": {
+        "size": 2542
+      },
+      "atomman/tools/indexstr.py": {
+        "size": 1119
+      },
+      "atomman/tools/miller.py": {
+        "size": 22878
+      },
+      "atomman/tools/vect_angle.py": {
+        "size": 1672
+      },
+      "atomman/unitconvert.py": {
+        "size": 6010
+      },
+      "conda_environment_settings/atomman.environment.yml": {
+        "size": 178
+      },
+      "conda_environment_settings/atomman_3_10.environment.yml": {
+        "size": 153
+      },
+      "conda_environment_settings/atomman_3_8.environment.yml": {
+        "size": 151
+      },
+      "conda_environment_settings/atomman_3_9.environment.yml": {
+        "size": 151
+      },
+      "doc/copytutorial.py": {
+        "size": 1907
+      },
+      "doc/html/_static/_sphinx_javascript_frameworks_compat.js": {
+        "size": 4418
+      },
+      "doc/html/_static/doctools.js": {
+        "size": 4472
+      },
+      "doc/html/_static/documentation_options.js": {
+        "size": 330
+      },
+      "doc/html/_static/jquery-3.4.1.js": {
+        "size": 280364
+      },
+      "doc/html/_static/jquery-3.5.1.js": {
+        "size": 287630
+      },
+      "doc/html/_static/jquery-3.6.0.js": {
+        "size": 288580
+      },
+      "doc/html/_static/jquery.js": {
+        "size": 89501
+      },
+      "doc/html/_static/language_data.js": {
+        "size": 4758
+      },
+      "doc/html/_static/searchtools.js": {
+        "size": 18732
+      },
+      "doc/html/_static/sphinx_highlight.js": {
+        "size": 5123
+      },
+      "doc/html/_static/underscore-1.13.1.js": {
+        "size": 68408
+      },
+      "doc/html/_static/underscore-1.3.1.js": {
+        "size": 35168
+      },
+      "doc/html/_static/underscore.js": {
+        "size": 19530
+      },
+      "doc/html/searchindex.js": {
+        "size": 262132
+      },
+      "doc/source/conf.py": {
+        "size": 5930
+      },
+      "doc/tutorial/files/2008--Mendelev-M-I--Al--A1--Cu--fcc--111sf.json": {
+        "size": 135074
+      },
+      "doc/tutorial/files/potential_LAMMPS_examples/comb-demo--LAMMPS--v2.json": {
+        "size": 1259
+      },
+      "doc/tutorial/files/potential_LAMMPS_examples/coul_long-demo--LAMMPS--v1.json": {
+        "size": 732
+      },
+      "doc/tutorial/files/potential_LAMMPS_examples/eam-demo--LAMMPS--v2.json": {
+        "size": 1180
+      },
+      "doc/tutorial/files/potential_LAMMPS_examples/eam_alloy-demo--LAMMPS--v1.json": {
+        "size": 1021
+      },
+      "doc/tutorial/files/potential_LAMMPS_examples/hybrid-demo--LAMMPS--v3.json": {
+        "size": 2289
+      },
+      "doc/tutorial/files/potential_LAMMPS_examples/lj_cut-demo--LAMMPS--v1.json": {
+        "size": 1868
+      },
+      "doc/tutorial/files/potential_LAMMPS_examples/meam-demo--LAMMPS--v1.json": {
+        "size": 1065
+      },
+      "pyproject.toml": {
+        "size": 147
+      },
+      "requirements.txt": {
+        "size": 114
+      },
+      "setup.py": {
+        "size": 1903
+      },
+      "tests/core/test_Atoms.py": {
+        "size": 2449
+      },
+      "tests/core/test_Box.py": {
+        "size": 9217
+      },
+      "tests/core/test_ElasticConstants.py": {
+        "size": 1053
+      },
+      "tests/core/test_NeighborList_and_nlist.py": {
+        "size": 2315
+      },
+      "tests/core/test_System.py": {
+        "size": 133
+      },
+      "tests/core/test_displacement.py": {
+        "size": 707
+      },
+      "tests/core/test_dmag_and_dvect.py": {
+        "size": 1411
+      },
+      "tests/defect/test_free_surface.py": {
+        "size": 7584
+      },
+      "tests/dump_load/test_atom_data.py": {
+        "size": 4885
+      },
+      "tests/dump_load/test_primitive_conventional.py": {
+        "size": 3095
+      },
+      "tests/plot/test_interpolate.py": {
+        "size": 692
+      },
+      "tests/region/test_plane.py": {
+        "size": 957
+      },
+      "tests/test_dummy.py": {
+        "size": 41
+      },
+      "tests/test_root.py": {
+        "size": 350
+      },
+      "tests/test_unitconvert.py": {
+        "size": 1493
+      },
+      "tests/tools/test_atomic_info.py": {
+        "size": 720
+      },
+      "tests/tools/test_axes_check.py": {
+        "size": 1236
+      },
+      "tests/tools/test_crystalsystem.py": {
+        "size": 4175
+      },
+      "tests/tools/test_duplicates_allclose.py": {
+        "size": 8880
+      },
+      "tests/tools/test_filltemplate.py": {
+        "size": 611
+      },
+      "tests/tools/test_indexstr.py": {
+        "size": 617
+      },
+      "tests/tools/test_miller.py": {
+        "size": 8396
+      },
+      "tests/tools/test_uber_open_rmode.py": {
+        "size": 1124
+      },
+      "tests/tools/test_vect_angle.py": {
+        "size": 518
+      }
+    },
+    "processed_by": "zip_fallback",
+    "success": true
+  },
+  "structure": {
+    "packages": [
+      "source.atomman",
+      "source.atomman.cluster",
+      "source.atomman.core",
+      "source.atomman.defect",
+      "source.atomman.dump",
+      "source.atomman.lammps",
+      "source.atomman.library",
+      "source.atomman.load",
+      "source.atomman.mep",
+      "source.atomman.plot",
+      "source.atomman.region",
+      "source.atomman.thermo",
+      "source.atomman.tools"
+    ]
+  },
+  "dependencies": {
+    "has_environment_yml": false,
+    "has_requirements_txt": true,
+    "pyproject": true,
+    "setup_cfg": false,
+    "setup_py": true
+  },
+  "entry_points": {
+    "imports": [],
+    "cli": [],
+    "modules": []
+  },
+  "llm_analysis": {
+    "core_modules": [
+      {
+        "package": "source.atomman.core",
+        "module": "Atoms",
+        "functions": [
+          "get_positions",
+          "set_positions",
+          "get_velocities",
+          "set_velocities"
+        ],
+        "classes": [
+          "Atoms"
+        ],
+        "description": "Handles atomic positions and velocities."
+      },
+      {
+        "package": "source.atomman.core",
+        "module": "Box",
+        "functions": [
+          "get_dimensions",
+          "set_dimensions"
+        ],
+        "classes": [
+          "Box"
+        ],
+        "description": "Defines the simulation box dimensions and transformations."
+      },
+      {
+        "package": "source.atomman.defect",
+        "module": "Dislocation",
+        "functions": [
+          "calculate_displacement",
+          "get_dislocation_line"
+        ],
+        "classes": [
+          "Dislocation"
+        ],
+        "description": "Models dislocations and calculates related properties."
+      },
+      {
+        "package": "source.atomman.lammps",
+        "module": "Potential",
+        "functions": [
+          "load_potential",
+          "evaluate_potential"
+        ],
+        "classes": [
+          "Potential"
+        ],
+        "description": "Handles LAMMPS potential files and evaluations."
+      },
+      {
+        "package": "source.atomman.plot",
+        "module": "plotly",
+        "functions": [
+          "plot_structure",
+          "plot_displacement"
+        ],
+        "classes": [],
+        "description": "Provides plotting capabilities using Plotly."
+      }
+    ],
+    "cli_commands": [],
+    "import_strategy": {
+      "primary": "import",
+      "fallback": "blackbox",
+      "confidence": 0.85
+    },
+    "dependencies": {
+      "required": [
+        "numpy",
+        "scipy",
+        "matplotlib"
+      ],
+      "optional": [
+        "plotly",
+        "ase"
+      ]
+    },
+    "risk_assessment": {
+      "import_feasibility": 0.8,
+      "intrusiveness_risk": "medium",
+      "complexity": "medium"
+    }
+  },
+  "deepwiki_analysis": {
+    "repo_url": "https://github.com/usnistgov/atomman",
+    "repo_name": "atomman",
+    "content": "usnistgov/atomman\nAtomistic Manipulation Toolkit\nRepository Not Indexed\nThis repository hasn't been indexed yet. Indexing allows you to explore code structure, find documentation, and understand dependencies.\nIndexing typically takes 2-10 minutes to complete after it starts indexing\nOnce indexed, you'll have full access to code exploration and search functionality",
+    "model": "gpt-4o-2024-08-06",
+    "source": "selenium",
+    "success": true
+  },
+  "deepwiki_options": {
+    "enabled": true,
+    "model": "gpt-4o-2024-08-06"
+  },
+  "risk": {
+    "import_feasibility": 0.8,
+    "intrusiveness_risk": "medium",
+    "complexity": "medium"
+  }
+}

atomman/mcp_output/diff_report.md

@@ -0,0 +1,63 @@
+# Atomman Project Difference Report
+
+## Project Overview
+
+**Repository:** Atomman  
+**Project Type:** Python Library  
+**Main Features:** Basic functionality for handling atomic structures and simulations.  
+**Report Date:** January 31, 2026  
+**Workflow Status:** Success  
+**Test Status:** Failed  
+
+The Atomman project is a Python library designed to facilitate the manipulation and analysis of atomic structures and simulations. It provides tools for creating, modifying, and analyzing atomic configurations, making it a valuable resource for researchers and developers working in materials science and computational physics.
+
+## Difference Analysis
+
+### Summary of Changes
+
+- **New Files Added:** 8
+- **Modified Files:** 0
+
+The recent update to the Atomman project involved the addition of eight new files. No existing files were modified in this update. The workflow status indicates that the integration process was successful, but the test status shows a failure, suggesting issues with the new additions.
+
+### New Files
+
+The eight new files introduced in this update likely contain new features or enhancements to the existing functionality. However, without modifications to existing files, it appears that these additions are standalone components or extensions.
+
+## Technical Analysis
+
+### Intrusiveness
+
+The update is classified as non-intrusive, meaning that the new files do not interfere with or alter the existing codebase. This suggests that the new features are designed to be modular and independent.
+
+### Test Failures
+
+The test failures indicate that the new files may not be functioning as intended or that they are not fully integrated with the existing system. The specific reasons for the test failures need to be identified and addressed to ensure the stability and reliability of the library.
+
+## Recommendations and Improvements
+
+1. **Investigate Test Failures:** Conduct a thorough analysis of the test results to identify the root causes of the failures. Focus on understanding how the new files interact with the existing system and where the breakdowns occur.
+
+2. **Enhance Testing Coverage:** Ensure that comprehensive test cases are developed for the new files. This includes unit tests, integration tests, and system tests to cover all possible scenarios and edge cases.
+
+3. **Documentation Update:** Update the project documentation to include information about the new features and how they can be utilized. This will help users understand the new capabilities and how to integrate them into their workflows.
+
+4. **Code Review:** Conduct a detailed code review of the new files to ensure they adhere to the project's coding standards and best practices. This can help identify potential issues early and improve code quality.
+
+## Deployment Information
+
+The deployment of the new files was successful, as indicated by the workflow status. However, due to the test failures, it is recommended to hold off on deploying these changes to a production environment until the issues are resolved.
+
+## Future Planning
+
+1. **Bug Fixes and Patches:** Prioritize fixing the issues identified in the test failures. Release patches as needed to address these problems promptly.
+
+2. **Feature Expansion:** Once the current issues are resolved, consider expanding the functionality of the new features based on user feedback and project goals.
+
+3. **Community Engagement:** Engage with the user community to gather feedback on the new features and identify areas for improvement or additional functionality.
+
+4. **Regular Updates:** Plan for regular updates to the library to incorporate new features, improvements, and bug fixes, ensuring the project remains relevant and useful to its users.
+
+## Conclusion
+
+The recent update to the Atomman project introduces new features through the addition of eight new files. While the integration was successful, test failures highlight the need for further investigation and resolution. By addressing these issues and enhancing testing and documentation, the project can continue to provide valuable tools for its users. Future planning should focus on expanding functionality and engaging with the community to drive the project's development forward.

atomman/mcp_output/mcp_plugin/adapter.py

@@ -0,0 +1,183 @@
+import os
+import sys
+
+# Path settings
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
+sys.path.insert(0, source_path)
+
+# Import statements
+try:
+    from atomman.core import Atoms, Box, ElasticConstants, System
+    from atomman.defect import FreeSurface, GrainBoundary
+    from atomman.tools import miller
+    import numpy as np
+    import scipy
+    import matplotlib.pyplot as plt
+except ImportError as e:
+    print(f"Import error: {e}. Ensure all dependencies are installed.")
+    # Fallback mode
+    mode = "blackbox"
+
+# Adapter class
+class Adapter:
+    """
+    Adapter class for MCP plugin, providing access to core functionalities
+    of the atomman package.
+    """
+
+    def __init__(self):
+        self.mode = "import"
+        if 'mode' in globals() and mode == "blackbox":
+            self.mode = "blackbox"
+            print("Running in fallback mode. Some functionalities may be limited.")
+
+    # Core module methods
+    # ------------------------------------------------------------------------
+
+    def create_atoms_instance(self, *args, **kwargs):
+        """
+        Create an instance of the Atoms class.
+
+        Parameters:
+        *args: Arguments for Atoms class.
+        **kwargs: Keyword arguments for Atoms class.
+
+        Returns:
+        dict: Status and instance of Atoms.
+        """
+        try:
+            atoms_instance = Atoms(*args, **kwargs)
+            return {"status": "success", "instance": atoms_instance}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    def create_box_instance(self, *args, **kwargs):
+        """
+        Create an instance of the Box class.
+
+        Parameters:
+        *args: Arguments for Box class.
+        **kwargs: Keyword arguments for Box class.
+
+        Returns:
+        dict: Status and instance of Box.
+        """
+        try:
+            box_instance = Box(*args, **kwargs)
+            return {"status": "success", "instance": box_instance}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    def create_elastic_constants_instance(self, *args, **kwargs):
+        """
+        Create an instance of the ElasticConstants class.
+
+        Parameters:
+        *args: Arguments for ElasticConstants class.
+        **kwargs: Keyword arguments for ElasticConstants class.
+
+        Returns:
+        dict: Status and instance of ElasticConstants.
+        """
+        try:
+            elastic_constants_instance = ElasticConstants(*args, **kwargs)
+            return {"status": "success", "instance": elastic_constants_instance}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    def create_system_instance(self, *args, **kwargs):
+        """
+        Create an instance of the System class.
+
+        Parameters:
+        *args: Arguments for System class.
+        **kwargs: Keyword arguments for System class.
+
+        Returns:
+        dict: Status and instance of System.
+        """
+        try:
+            system_instance = System(*args, **kwargs)
+            return {"status": "success", "instance": system_instance}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    # Defect module methods
+    # ------------------------------------------------------------------------
+
+    def create_free_surface_instance(self, *args, **kwargs):
+        """
+        Create an instance of the FreeSurface class.
+
+        Parameters:
+        *args: Arguments for FreeSurface class.
+        **kwargs: Keyword arguments for FreeSurface class.
+
+        Returns:
+        dict: Status and instance of FreeSurface.
+        """
+        try:
+            free_surface_instance = FreeSurface(*args, **kwargs)
+            return {"status": "success", "instance": free_surface_instance}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    def create_grain_boundary_instance(self, *args, **kwargs):
+        """
+        Create an instance of the GrainBoundary class.
+
+        Parameters:
+        *args: Arguments for GrainBoundary class.
+        **kwargs: Keyword arguments for GrainBoundary class.
+
+        Returns:
+        dict: Status and instance of GrainBoundary.
+        """
+        try:
+            grain_boundary_instance = GrainBoundary(*args, **kwargs)
+            return {"status": "success", "instance": grain_boundary_instance}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    # Tools module methods
+    # ------------------------------------------------------------------------
+
+    def call_miller_function(self, *args, **kwargs):
+        """
+        Call the miller function.
+
+        Parameters:
+        *args: Arguments for miller function.
+        **kwargs: Keyword arguments for miller function.
+
+        Returns:
+        dict: Status and result of miller function.
+        """
+        try:
+            result = miller(*args, **kwargs)
+            return {"status": "success", "result": result}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    # Utility methods
+    # ------------------------------------------------------------------------
+
+    def plot_data(self, data):
+        """
+        Plot data using matplotlib.
+
+        Parameters:
+        data: Data to be plotted.
+
+        Returns:
+        dict: Status of the plotting operation.
+        """
+        try:
+            plt.plot(data)
+            plt.show()
+            return {"status": "success"}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+# End of Adapter class
+# ------------------------------------------------------------------------

atomman/mcp_output/mcp_plugin/main.py

@@ -0,0 +1,13 @@
+"""
+MCP Service Auto-Wrapper - Auto-generated
+"""
+from mcp_service import create_app
+
+def main():
+    """Main entry point"""
+    app = create_app()
+    return app
+
+if __name__ == "__main__":
+    app = main()
+    app.run()

atomman/mcp_output/mcp_plugin/mcp_service.py

@@ -0,0 +1,165 @@
+import os
+import sys
+
+# Add the local source directory to sys.path
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
+if source_path not in sys.path:
+    sys.path.insert(0, source_path)
+
+from fastmcp import FastMCP
+from atomman.core import Atoms, Box, ElasticConstants, System
+from atomman.defect import FreeSurface, GrainBoundary
+from atomman.tools import miller, vect_angle
+
+# Create the FastMCP service application
+mcp = FastMCP("atomman_service")
+
+@mcp.tool(name="create_atoms", description="Create an Atoms object")
+def create_atoms(positions: list, symbols: list) -> dict:
+    """
+    Create an Atoms object.
+
+    Parameters:
+    - positions: List of atomic positions.
+    - symbols: List of atomic symbols.
+
+    Returns:
+    - Dictionary with success status and Atoms object.
+    """
+    try:
+        atoms = Atoms(positions=positions, symbols=symbols)
+        return {"success": True, "result": atoms}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+@mcp.tool(name="create_box", description="Create a Box object")
+def create_box(vects: list) -> dict:
+    """
+    Create a Box object.
+
+    Parameters:
+    - vects: List of box vectors.
+
+    Returns:
+    - Dictionary with success status and Box object.
+    """
+    try:
+        box = Box(vects=vects)
+        return {"success": True, "result": box}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+@mcp.tool(name="calculate_elastic_constants", description="Calculate elastic constants")
+def calculate_elastic_constants(C: list) -> dict:
+    """
+    Calculate elastic constants.
+
+    Parameters:
+    - C: List of elastic constants.
+
+    Returns:
+    - Dictionary with success status and ElasticConstants object.
+    """
+    try:
+        elastic_constants = ElasticConstants(C=C)
+        return {"success": True, "result": elastic_constants}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+@mcp.tool(name="create_system", description="Create a System object")
+def create_system(atoms: Atoms, box: Box) -> dict:
+    """
+    Create a System object.
+
+    Parameters:
+    - atoms: Atoms object.
+    - box: Box object.
+
+    Returns:
+    - Dictionary with success status and System object.
+    """
+    try:
+        system = System(atoms=atoms, box=box)
+        return {"success": True, "result": system}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+@mcp.tool(name="generate_free_surface", description="Generate a free surface")
+def generate_free_surface(system: System, miller_indices: list) -> dict:
+    """
+    Generate a free surface.
+
+    Parameters:
+    - system: System object.
+    - miller_indices: List of Miller indices.
+
+    Returns:
+    - Dictionary with success status and FreeSurface object.
+    """
+    try:
+        surface = FreeSurface(system=system, miller=miller_indices)
+        return {"success": True, "result": surface}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+@mcp.tool(name="calculate_grain_boundary", description="Calculate a grain boundary")
+def calculate_grain_boundary(system: System, plane: list) -> dict:
+    """
+    Calculate a grain boundary.
+
+    Parameters:
+    - system: System object.
+    - plane: List defining the grain boundary plane.
+
+    Returns:
+    - Dictionary with success status and GrainBoundary object.
+    """
+    try:
+        boundary = GrainBoundary(system=system, plane=plane)
+        return {"success": True, "result": boundary}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+@mcp.tool(name="calculate_miller_indices", description="Calculate Miller indices")
+def calculate_miller_indices(vectors: list) -> dict:
+    """
+    Calculate Miller indices.
+
+    Parameters:
+    - vectors: List of vectors.
+
+    Returns:
+    - Dictionary with success status and Miller indices.
+    """
+    try:
+        indices = miller(vectors)
+        return {"success": True, "result": indices}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+@mcp.tool(name="calculate_vector_angle", description="Calculate angle between vectors")
+def calculate_vector_angle(vector1: list, vector2: list) -> dict:
+    """
+    Calculate angle between two vectors.
+
+    Parameters:
+    - vector1: First vector.
+    - vector2: Second vector.
+
+    Returns:
+    - Dictionary with success status and angle in degrees.
+    """
+    try:
+        angle = vect_angle(vector1, vector2)
+        return {"success": True, "result": angle}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+def create_app() -> FastMCP:
+    """
+    Create and return the FastMCP application instance.
+
+    Returns:
+    - FastMCP instance.
+    """
+    return mcp

atomman/mcp_output/requirements.txt

@@ -0,0 +1,16 @@
+fastmcp
+fastapi
+uvicorn[standard]
+pydantic>=2.0.0
+xmltodict
+numericalunits
+DataModelDict
+numpy>=1.15
+scipy
+pandas
+matplotlib
+cython
+requests
+toolz
+potentials==0.3.8
+yabadaba>=0.3.2

atomman/mcp_output/start_mcp.py

@@ -0,0 +1,30 @@
+
+"""
+MCP Service Startup Entry
+"""
+import sys
+import os
+
+project_root = os.path.dirname(os.path.abspath(__file__))
+mcp_plugin_dir = os.path.join(project_root, "mcp_plugin")
+if mcp_plugin_dir not in sys.path:
+    sys.path.insert(0, mcp_plugin_dir)
+
+from mcp_service import create_app
+
+def main():
+    """Start FastMCP service"""
+    app = create_app()
+    # Use environment variable to configure port, default 8000
+    port = int(os.environ.get("MCP_PORT", "8000"))
+    
+    # Choose transport mode based on environment variable
+    transport = os.environ.get("MCP_TRANSPORT", "stdio")
+    if transport == "http":
+        app.run(transport="http", host="0.0.0.0", port=port)
+    else:
+        # Default to STDIO mode
+        app.run()
+
+if __name__ == "__main__":
+    main()

atomman/mcp_output/workflow_summary.json

@@ -0,0 +1,207 @@
+{
+  "repository": {
+    "name": "atomman",
+    "url": "https://github.com/usnistgov/atomman",
+    "local_path": "/export/zxcpu1/shiweijie/code/ghh/Code2MCP/workspace/atomman",
+    "description": "Python library",
+    "features": "Basic functionality",
+    "tech_stack": "Python",
+    "stars": 0,
+    "forks": 0,
+    "language": "Python",
+    "last_updated": "",
+    "complexity": "medium",
+    "intrusiveness_risk": "medium"
+  },
+  "execution": {
+    "start_time": 1769829596.3015447,
+    "end_time": 1769829691.7475183,
+    "duration": 95.44597387313843,
+    "status": "success",
+    "workflow_status": "success",
+    "nodes_executed": [
+      "download",
+      "analysis",
+      "env",
+      "generate",
+      "run",
+      "review",
+      "finalize"
+    ],
+    "total_files_processed": 13,
+    "environment_type": "unknown",
+    "llm_calls": 0,
+    "deepwiki_calls": 0
+  },
+  "tests": {
+    "original_project": {
+      "passed": false,
+      "details": {},
+      "test_coverage": "100%",
+      "execution_time": 0,
+      "test_files": []
+    },
+    "mcp_plugin": {
+      "passed": true,
+      "details": {},
+      "service_health": "healthy",
+      "startup_time": 0,
+      "transport_mode": "stdio",
+      "fastmcp_version": "unknown",
+      "mcp_version": "unknown"
+    }
+  },
+  "analysis": {
+    "structure": {
+      "packages": [
+        "source.atomman",
+        "source.atomman.cluster",
+        "source.atomman.core",
+        "source.atomman.defect",
+        "source.atomman.dump",
+        "source.atomman.lammps",
+        "source.atomman.library",
+        "source.atomman.load",
+        "source.atomman.mep",
+        "source.atomman.plot",
+        "source.atomman.region",
+        "source.atomman.thermo",
+        "source.atomman.tools"
+      ]
+    },
+    "dependencies": {
+      "has_environment_yml": false,
+      "has_requirements_txt": true,
+      "pyproject": true,
+      "setup_cfg": false,
+      "setup_py": true
+    },
+    "entry_points": {
+      "imports": [],
+      "cli": [],
+      "modules": []
+    },
+    "risk_assessment": {
+      "import_feasibility": 0.8,
+      "intrusiveness_risk": "medium",
+      "complexity": "medium"
+    },
+    "deepwiki_analysis": {
+      "repo_url": "https://github.com/usnistgov/atomman",
+      "repo_name": "atomman",
+      "content": "usnistgov/atomman\nAtomistic Manipulation Toolkit\nRepository Not Indexed\nThis repository hasn't been indexed yet. Indexing allows you to explore code structure, find documentation, and understand dependencies.\nIndexing typically takes 2-10 minutes to complete after it starts indexing\nOnce indexed, you'll have full access to code exploration and search functionality",
+      "model": "gpt-4o-2024-08-06",
+      "source": "selenium",
+      "success": true
+    },
+    "code_complexity": {
+      "cyclomatic_complexity": "medium",
+      "cognitive_complexity": "medium",
+      "maintainability_index": 75
+    },
+    "security_analysis": {
+      "vulnerabilities_found": 0,
+      "security_score": 85,
+      "recommendations": []
+    }
+  },
+  "plugin_generation": {
+    "files_created": [
+      "mcp_output/start_mcp.py",
+      "mcp_output/mcp_plugin/__init__.py",
+      "mcp_output/mcp_plugin/mcp_service.py",
+      "mcp_output/mcp_plugin/adapter.py",
+      "mcp_output/mcp_plugin/main.py",
+      "mcp_output/requirements.txt",
+      "mcp_output/README_MCP.md"
+    ],
+    "main_entry": "start_mcp.py",
+    "requirements": [
+      "fastmcp>=0.1.0",
+      "pydantic>=2.0.0"
+    ],
+    "readme_path": "/export/zxcpu1/shiweijie/code/ghh/Code2MCP/workspace/atomman/mcp_output/README_MCP.md",
+    "adapter_mode": "import",
+    "total_lines_of_code": 0,
+    "generated_files_size": 0,
+    "tool_endpoints": 0,
+    "supported_features": [
+      "Basic functionality"
+    ],
+    "generated_tools": [
+      "Basic tools",
+      "Health check tools",
+      "Version info tools"
+    ]
+  },
+  "code_review": {},
+  "errors": [],
+  "warnings": [],
+  "recommendations": [
+    "Improve test coverage by adding more unit tests for uncovered modules",
+    "optimize large files by breaking them into smaller",
+    "more manageable components",
+    "ensure consistent use of docstrings and comments for better code readability",
+    "update the documentation to reflect recent changes and improvements",
+    "consider indexing the repository for better code exploration and search functionality",
+    "review and optimize dependencies to ensure only necessary packages are included",
+    "enhance the import strategy to increase feasibility and reduce intrusiveness risk",
+    "improve the setup process by including a `setup.cfg` file for better configuration management",
+    "streamline the plugin integration process by ensuring all endpoints are thoroughly tested",
+    "conduct a performance review to identify and address any bottlenecks or inefficiencies."
+  ],
+  "performance_metrics": {
+    "memory_usage_mb": 0,
+    "cpu_usage_percent": 0,
+    "response_time_ms": 0,
+    "throughput_requests_per_second": 0
+  },
+  "deployment_info": {
+    "supported_platforms": [
+      "Linux",
+      "Windows",
+      "macOS"
+    ],
+    "python_versions": [
+      "3.8",
+      "3.9",
+      "3.10",
+      "3.11",
+      "3.12"
+    ],
+    "deployment_methods": [
+      "Docker",
+      "pip",
+      "conda"
+    ],
+    "monitoring_support": true,
+    "logging_configuration": "structured"
+  },
+  "execution_analysis": {
+    "success_factors": [
+      "Successful execution of all workflow nodes",
+      "Healthy service status of the MCP plugin"
+    ],
+    "failure_reasons": [],
+    "overall_assessment": "excellent",
+    "node_performance": {
+      "download_time": "Completed successfully, indicating efficient data retrieval",
+      "analysis_time": "Completed successfully, indicating effective code analysis",
+      "generation_time": "Completed successfully, indicating efficient code generation",
+      "test_time": "Original project tests failed, but MCP plugin tests passed"
+    },
+    "resource_usage": {
+      "memory_efficiency": "No data available for memory usage",
+      "cpu_efficiency": "No data available for CPU usage",
+      "disk_usage": "Generated files are minimal in size, indicating efficient disk usage"
+    }
+  },
+  "technical_quality": {
+    "code_quality_score": 75,
+    "architecture_score": 80,
+    "performance_score": 70,
+    "maintainability_score": 75,
+    "security_score": 85,
+    "scalability_score": 70
+  }
+}

atomman/source/LICENSE.TXT

@@ -0,0 +1,17 @@
+Licensing
+=========
+
+License Information for NIST data (other than Standard Reference Data (SRD))
+
+This data was developed by employees of the National Institute of Standards and Technology (NIST), an agency of the Federal Government. Pursuant to title 15 United States Code Section 105, works of NIST employees are not subject to copyright protection in the United States and are considered to be in the public domain.
+
+The data is provided by NIST as a public service and is expressly provided “AS IS.” NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. NIST does not warrant or make any representations regarding the use of the data or the results thereof, including but not limited to the correctness, accuracy, reliability or usefulness of the data. NIST SHALL NOT BE LIABLE AND YOU HEREBY RELEASE NIST FROM LIABILITY FOR ANY INDIRECT, CONSEQUENTIAL, SPECIAL, OR INCIDENTAL DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE), WHETHER ARISING IN TORT, CONTRACT, OR OTHERWISE, ARISING FROM OR RELATING TO THE DATA (OR THE USE OF OR INABILITY TO USE THIS DATA), EVEN IF NIST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+To the extent that NIST may hold copyright in countries other than the United States, you are hereby granted the non-exclusive irrevocable and unconditional right to print, publish, prepare derivative works and distribute the NIST data, in any medium, or authorize others to do so on your behalf, on a royalty-free basis throughout the World.
+
+You may improve, modify, and create derivative works of the data or any portion of the data, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the data and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the data.
+
+Permission to use this data is contingent upon your acceptance of the terms of this agreement and upon your providing appropriate acknowledgments of NIST’s creation of the data.
+
+Copyright Protection for NIST Standard Reference Data (SRD)
+
+Copyright protection on this compilation of data has been secured by the U.S. Department of Commerce in the United States and in other countries that are parties to the Universal Copyright Convention, pursuant to Section 290(e) of Title 15 of the United States Code. NIST Standard Reference Data (SRD); ©Copyright ©2013 by the U.S. Secretary of Commerce on behalf of the United States of America. All rights reserved.

atomman/source/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.rst
+include atomman/VERSION
+include UPDATES.rst
+include LICENSE.TXT
+
+include atomman/core/*.pyx
+include atomman/core/*.pxd
+include atomman/defect/*.pyx
+include atomman/defect/*.pyd

atomman/source/README.rst

@@ -0,0 +1,112 @@
+AtomMan
+=======
+
+Atomistic Manipulation Toolkit
+
+AtomMan: the Atomistic Manipulation Toolkit is a Python library for
+creating, representing, manipulating, and analyzing large-scale atomic
+systems of atoms. The focus of the package is to facilitate the rapid design
+and development of simulations that are fully documented and easily adaptable
+to new potentials, configurations, etc.  The code has no requirements that
+limit which systems it can be used on, i.e. it should work on Linux, Mac and
+Windows computers.
+
+Features:
+
+1. Allows for efficient and fast calculations on millions of atoms, each with
+   many freely defined per-atom properties.
+
+2. Built-in tools for generating and analyzing crystalline defects, such as
+   point defects, stacking faults, and dislocations.
+
+4. Call LAMMPS directly from Python and instantly retrieve the resulting data
+   or LAMMPS error statement.
+
+5. Easily convert systems to/from the other Python atomic representations, such
+   as ase.Atoms and pymatgen.Structure.
+
+6. Can read and dump crystal structure information from a number of formats,
+   such as LAMMPS data and dump files, and POSCAR.
+
+7. Built-in unit conversions.
+
+Installation
+------------
+
+The atomman package is compatible with Python 3.7+.
+
+The latest release can be installed using pip::
+
+    pip install atomman
+
+or using conda from the conda-forge channel::
+
+    conda install -c conda-forge atomman
+
+For Windows users, it is recommended to use an Anaconda distribution and use
+conda to install numpy, scipy, matplotlib, pandas and cython prior to
+installing atomman.
+
+Alternatively, all code and documentation can be downloaded from GitHub.
+
+- The stable releases are available at
+  `https://github.com/usnistgov/atomman <https://github.com/usnistgov/atomman>`__.
+
+- The working development versions are at
+  `https://github.com/lmhale99/atomman <https://github.com/lmhale99/atomman>`__.
+    
+Documentation
+-------------
+
+Web-based documentation for the atomman package is available at
+`https://www.ctcms.nist.gov/potentials/atomman <https://www.ctcms.nist.gov/potentials/atomman>`__.
+
+Source code for the documentation can be found in the
+`github doc directory <https://github.com/usnistgov/atomman/tree/master/doc/>`__.
+The doc directory contains the information both as the source RestructuredText
+files and as unformatted HTML. If you download a copy, you can view the HTML
+version offline by
+
+    cd {atomman_path}/doc/html
+    python -m http.server
+
+Then, opening localhost:8000 in a web browser.
+
+The documentation consists of two main components:
+
+1. **Tutorial Jupyter Notebooks:**
+   `Online html version <https://www.ctcms.nist.gov/potentials/atomman/tutorial/index.html>`__,
+   `Downloadable Notebook version <https://github.com/usnistgov/atomman/tree/master/doc/tutorial>`__.
+   The tutorials starting with ##. provide a general overview/example of the
+   various capabilities.  The tutorials starting with ##.#. give more detailed
+   descriptions and list options available to the tools mentioned in the
+   overview tutorials.
+
+2. **Code Documentation:**
+   `Online html version <https://www.ctcms.nist.gov/potentials/atomman/atomman.html>`__.
+   This provides a rendering of the Python docstrings for the included
+   functions and classes.
+
+
+Optional packages
+-----------------
+
+This is a list of additional Python packages that are needed for some of the
+optional features of the package.
+
+- `diffpy.Structure <http://www.diffpy.org/diffpy.Structure/>`__:
+  CIF reader. Required for loading systems from CIF files.
+
+- `ase <https://wiki.fysik.dtu.dk/ase/>`__:
+  The Atomic Simulation Environment for interacting with small systems
+  and DFT calculations. Required for converting to/from ase.Atoms objects.
+
+- `pymatgen <http://pymatgen.org/>`__:
+  The Python Materials Genomics package used by the Materials
+  Project for DFT calculations. Required for converting to/from
+  pymatgen.Structure objects.
+
+- `spglib <https://atztogo.github.io/spglib/python-spglib.html>`__:
+  A Python interface to the spglib spacegroup analysis code.  spglib
+  can be used to analyze and determine the spacegroup for an atomic system.
+  Required for converting to/from spglib.cell objects.

atomman/source/UPDATES.rst

@@ -0,0 +1,682 @@
+Updates
+=======
+
+Version 1.5.2
+-------------
+
+- **atomman.ElasticConstants2** added as an alternative.  This likely
+  behaves the same as the original, but with improvements in representations
+  of the various crystal families.  Separate for now as I haven't had the
+  chance to fully verify it.
+
+- **atomman.library.Database.download_all() no longer downloads relaxed_crystal
+  records.  There are too many for this method to be practical.
+
+- **atomman.lammps.run** now reads errors from log files if screen = False.
+  This should hopefully avoid LAMMPSErrors that have no message.
+
+- bug fixes for atomman.Box.position_cartesian_to_relative(),
+  atomman.library.Database.get_relaxed_crystal(), atomman.defect.GrainBoundary,
+  and atomman.defect.TiltGrainBoundaryHelper.
+
+Version 1.5.1
+-------------
+
+- **atomman.unitconvert** has been updated to use yabadaba.UnitConverter
+  ensuring full compatibility between unit conversions with the two packages.
+  Despite the code changing, atomman.unitconvert should still behave
+  identically to before. **WARNING**: make sure yabadaba is at least version
+  0.3.2 to fix a bug associated this change!!!
+
+- **atomman.defect.GRIP** added that manages inputs for the grand-canonical
+  interface predictor (GRIP) algorithm for grain boundary generation and
+  relaxation.
+  
+- **atomman.defect.GrainBoundary.from_model** class method is added that reads
+  in grain boundary configuration information from a grain_boundary record.
+
+- **atomman.defect.GrainBoundary.dlat** method added that computes the lattice
+  thickness for the grain boundary interface, which is used by GRIP.
+
+- Miller vector support added to **atomman.library.record.GrainBoundary**.
+
+- Some code cleanup and reorganization in **atomman.defect.Boundary.dlat**.
+
+- **atomman.Box.d_hkl** method added for computing interplanar spacings.
+
+- **atomman.mep.ISMPath** updated to use tqdm for the calculation status 
+  progress rather than print statements.
+  
+- **atomman.defect.InterstitialSite** added, which uses Voronoi analysis to
+  identify interstitial sites in a given system.
+
+- **atomman.lammps.newseed** method added that generates a new
+  LAMMPS-compatible random number seed.  **atomman.lammps.seed** method added
+  that tests if a given int can be used as a LAMMPS random number seed.
+
+- **atomman.lammps.run** tinkered with again related to trying to get the
+  LAMMPS errors to be passed to python in an informative way.
+
+- Minor doc and docstring updates for typos and syntax warnings.
+
+Version 1.5.0
+-------------
+
+- Overhaul of the Record objects with the new yabadaba version that greatly
+  reduces the code and better generalizes record interactions.
+
+- Fixes to support numpy 2.0.
+
+- **atomman.lammps.run** now has a partition parameter to support multi-replica
+  simulations, like NEB and temperature-accelerated dynamics.  Updates (again)
+  to hopefully print better error messages extracted from LAMMPS runs.
+
+- **atomman.defect.SurfaceEnergyEstimator** and
+  **atomman.defect.surface_energy_estimate()** added that provide quick
+  estimates of high index free surface energies based on a few low index values.
+  The former is a class for performing the calculations, and the latter a
+  function.
+
+- Bug fix for **ase_Atoms** dump to use scaled positions instead of absolute to
+  ensure box and atoms remain aligned with the loss of box origin control.
+
+- **atomman.tools.miller.tostring** method added for generating Miller indices
+  strings for planes and vectors.  This serves as the inverse function of
+  fromstring.
+
+- **standardize_cell** dump style added that serves as a wrapper around the
+  more generalized spglib.standardize_cell() method for identifying and
+  normalizing systems to their corresponding unit cells.
+
+- **Database.fetch_mp_crystal(s)** have been updated for the new Materials
+  Project APIs.
+
+Version 1.4.11
+--------------
+
+- The structure generation methods of **atomman.defect.Dislocation** now all
+  have a center parameter that allows for the dislocation's position to be
+  shifted.  This is useful for setting up NEB runs.
+
+- **atomman.lammps.run** now supports lammps_command paths that contain spaces.
+
+- **atomman.defect.Boundary** has been further improved and some supporting
+  tools developed.  Not fully finalized yet.
+
+- **neb_replica** dump style added that creates the atomic configurations used
+  by LAMMPS for defining the final (and intermediate) replicas.
+  
+- More tools and operations related to Miller crystal vectors and planes have
+  been added.  These should make it possible for future revisions of the
+  defect generators to be simplified and made more uniform.
+
+- Record classes have been updated to support a URL field for assigning
+  persistent identification (PID) values once uploaded to a CDCS database.
+
+Version 1.4.10
+--------------
+
+- **atomman.lammps.Log** now has more options during flatten allowing for only
+  a subset of simulation runs to be merged together.  Bug fix related to type
+  identification during flatten.
+
+- **pdb** dump style for protein database file format.  Mostly useful for the
+  plotting tools that natively interpret this format.
+
+- Transformations added to support hexagonal conventional cells of trigonal
+  systems. These 't1' and 't2' options are now available in
+  **atomman.tools.miller.vector_conventional_to_primitive**, 
+  **atomman.tools.miller.vector_primitive_to_conventional**,
+  and the **conventional_to_primitive** and **primitive_to_conventional** dump
+  styles.
+
+- **atomman.tools.miller.fromstring** method added for interpreting formatted
+  string representations of Miller vectors and planes as numpy arrays.
+
+- From **atomman.defect**, **FreeSurface**, **StackingFault** and
+  **Dislocation** now have fromrecord() and fromdatabase() methods.  The
+  fromrecord() methods read in parameters from an associated defect parameter
+  set record, and fromdatabase() allows for a matching defect parameter set
+  record to be fetched from a database. 
+
+- **atomman.defect.Dislocation** updated to recognize Miller-Bravais 4 index
+  vectors and planes.
+
+- All Record classes now have a "database" attribute that sets a default
+  database to associate with the record.  This makes it possible for the Record
+  classes to have methods that fetch additional content from the database as
+  needed.
+
+- **atomman.defect.Boundary** class added for generating phase boundary and
+  grain boundary systems.  The basic core of the generator is there and works
+  for cubic systems.  To be improved in the next few versions as time allows.
+
+- **atomman.plot** has new methods to allow for interactive 3D plots when
+  working in a Jupyter environment.  Substantial changes to these plotting
+  tools likely in subsequent versions of atomman.
+
+Version 1.4.9
+-------------
+
+- **atomman.thermo.RDF** updates to support more general use.
+
+- Handling of record queries updated to be consistent with yabadaba 0.2.0.
+
+Version 1.4.8
+-------------
+
+- **atomman.thermo** module added that provides tools and reference models
+  related to thermodynamic calculations.
+
+- **atomman.tools.vect_angle** updated to allow for comparisons of multiple
+  vector values at once.
+
+- **conventional_to_primitive** and **primitive_to_conventional** dump styles
+  added that convert between standard conventional and primitive unit cell
+  settings.  These were created to make it easy to generate compatible cells
+  in the two settings for performing crystal and lattice vector operations.
+
+- **atomman.tools.miller.vector_conventional_to_primitive** and 
+  **atomman.tools.miller.vector_primitive_to_conventional** transformation
+  operations for face-centered basis settings have been changed to coincide
+  with the new dump methods above.
+
+- **atomman.defect.VolterraDislocation** classes now support specifying the m
+  and n dislocation axes using str 'x', 'y', 'z' values.  The dislocation
+  transformation basis code is now integrated into the class as well.
+
+- **atomman.defect.Dislocation** A new init parameter ucell_setting allows for
+  the lattice setting of the ucell to be given so that all lattice vectors can
+  be used and explored rather than just integer crystal vectors relative to
+  ucell.  Also, a dipole method has been added that allows for the generation
+  of stable dislocation dipole atomic configurations.
+
+- **atomman.defect.Strain** bug fix related to numpy changing how irregular
+  arrays are represented.
+
+- **atomman.plot.interpolate_contour** figsize option fixed and improved.
+
+Version 1.4.7
+-------------
+
+- **atomman.load** Import of load styles is now fully modular. Note that as a 
+  result of this, the individual **load_{style}** function calls have been
+  removed.
+
+- **atomman.load** and **atomman.dump** Fix to make the individual load
+  and dump styles optional dependent on any additional package requirements.
+  Versions 1.4.4-1.4.6 accidentally required that these optional packages be
+  installed.
+
+- **atomman.lammps.Log.flatten** Fix for a rare case associated with stopped
+  LAMMPS simulations and restarts that occasionally resulted in columns
+  inadvertently being interpreted as str values instead of float values. 
+
+Version 1.4.6
+-------------
+
+- Import of dump styles is now fully modular and delayed.  This allows for
+  new styles to be introduced that have additional package requirements without
+  breaking all of atomman. The delayed loading also makes it possible for dump
+  methods to call other dump or load methods without import errors. Note that 
+  as a result of this, the individual **dump_{style}** function calls have been
+  removed.
+
+- **atomman.dump.primitive_cell** now works properly because of the above.
+
+- Internal use of **atomman.tools.crystalsystem** functions changed to use the
+  corresponding **atomman.Box** methods introduced in 1.4.4. instead.
+
+- XSL and XSD files added for the defined record styles to better support
+  integration of the reference records with potentials.nist.gov.
+
+
+Version 1.4.5
+-------------
+
+- **atomman.defect.FreeSurface** now has a unique_shifts() method that uses
+  crystal symmetry to filter out most symmetrically equivalent termination
+  planes.
+
+- **atomman.dump.primitive_cell** has been added that uses spglib to take an
+  atomic system and return a new system corresponding to the identified
+  primitive unit cell.
+
+- **atomman.dump.phonopy_Atoms** is updated for newer versions of phonopy.
+
+- **strain** methods have been added to **atomman.defect.VolterraDislocation**
+  and its subclasses to provide the strain associated with the dislocation
+  solutions.  Stress and displacement methods in **atomman.defect.Stroh** have
+  been adjusted to improve calculation speed.
+
+- **atomman.defect.pn_arctan_disldensity** added and 
+  **atomman.defect.pn_arctan_disregistry** updated for consistency and new
+  options.  These give classic Peierls-Nabarro dislocation width models.
+
+- **load_table** method has been added to **atomman.cluster.BondAngleMap**
+  allowing for the data generated by save_table to be read back in.
+
+Version 1.4.4
+-------------
+
+- New methods added to **atomman.Box**
+
+  - **reciprocal_vects** method added that computes the reciprocal lattice
+    vectors associated with the Box's vectors.
+
+  - **vector_crystal_to_cartesian** and **plane_crystal_to_cartesian** from
+    **atomman.tools.miller** have been added as Box methods.
+
+  - **position_relative_to_cartesian** replaces **atomman.System.unscale** and
+    **position_cartesian_to_relative** replaces **atomman.System.scale** as the
+    new operations are better named and only relate to Box information.
+
+  - **identifyfamily**, **iscubic**, **ishexagonal**, **istetragonal**,
+    **isrhombohedral**, **isorthorhombic**, **ismonoclinic** and
+    **ismonoclinic** methods added from **atomman.tools**.
+
+- **atomman.region.Plane** has new methods **operate**, **__eq__** and
+  **isclose** for transforming and comparing Planes.
+
+- **atomman.plot.interpolate_contour** reworked to allow 
+  matplotlib.pyplot.axes to be passed through allowing for the color contour
+  plots to be added on top of existing plots.  Options also added to turn off
+  features.
+
+- **atomman.defect.DifferentialDisplacement** has new plot_with_nye method that
+  overlays Nye tensor color contours with the differential displacement plots.
+
+- Overhaul of **atomman.library** operations reflecting that underlying
+  database handling is now branched off into the separate yabadaba package.
+
+- **Dislocation**, **FreeSurface**, **PointDefect** and **StackingFault**
+  Record classes related to defect parameter sets have been moved from iprPy
+  to **atomman.library.record**  This is to support future updates where these
+  parameter sets can be directly passed to the defect generator classes.
+
+- Typing hints added to all of atomman's code.
+
+Version 1.4.3
+-------------
+
+- **atomman.library.Database** query options better ordered and default values
+  updated.  retrieve methods added to allow for database records to be copied
+  to local files.
+
+- Bug fix for composition queries of relaxed and reference crystal records.
+
+- Updates for KIM model handling due to updates with the potentials package.
+
+
+Version 1.4.2
+-------------
+
+- **atomman.dump.pymatgen_Structure** updated for new pymatgen versions.
+
+- **atomman.defect.DifferentialDisplacement** bug fix related to handling
+  the atomcolor and atomcmap parameters.
+
+- **atomman.tools** now imports aslist, iaslist, screen_input, uber_open_rmode,
+  and atomic_info from potentials to remove duplicate code. 
+
+- **atomman.library** various updates related to keeping record handling
+  consistent with updates in potentials version 0.3.1.
+
+Version 1.4.1
+-------------
+
+- **atomman.lammps.Log** bug fix for properly reading performance data
+  for restart runs.
+
+Version 1.4.0
+-------------
+
+- **atomman.library** and **atomman.settings** modules updated to reflect
+  the reworked potentials package version 0.3.0.
+
+- **atomman.load_lammps_potential** and **atomman.load** options 'prototype'
+  and 'crystal' updated for the new library module.  load style
+  'dft_reference' added.
+
+- **atomman.lammps.Potential** now is a function that returns either a 
+  potentials.record.PotentialLAMMPS or potentials.record.PotentialLAMMPSKIM
+  object.
+
+- **atomman.lammps.run** now has options for passing string input scripts
+  rather than reading from files, and for turning off log file output.
+  **atomman.lammps.checkversion** simplified due to the changes to run.
+
+- **atomman.cluster.BondAngleMap** added for characterizing the three-body
+  interactions as predicted by interatomic potentials.  
+
+Version 1.3.7
+-------------
+
+- **atomman.dump.atom_data** bug fix for kim model potentials (now they work).
+
+- **atomman.lammps.Log** now captures performance output.  A Simulation class
+  is added to better represent each run/simulation.  The flatten method is 
+  updated to return a new Simulation rather than overwriting the current data.
+  New 'all' style added to flatten that will merge all runs without filtering
+  out duplicate timesteps. 
+
+- **atomman.defect.differential_displacement** option added to pass an existing
+  matplotlib axes object to plot on rather than generating a new figure.  This
+  allows for subplots to be constructed.
+
+- **atomman.defect.DifferentialDisplacement** option added to pass an existing
+  matplotlib axes object to plot on rather than generating a new figure.  This
+  allows for subplots to be constructed.
+
+- **atomman.mep** subpackage added for performing minimum energy pathway
+  calculations. The contained Path classes represent an energy path and have
+  built-in iteration methods.  The ISMPath uses the improved string method.
+
+  **atomman.defect.GammaSurface** updated with path and build_path methods
+  that help build mep Path objects for the GammaSurface.
+
+  **atomman.defect.Strain** class added that improves upon the nye_tensor
+  function.  The new class uses Cython for roughly a 2X speedup and is
+  designed to be easier to use.  
+
+  **atomman.defect.SDVPN** The sign of tau used by stress_energy with
+  fullstress=False is flipped to correspond to the behavior of 
+  stress_energy with fullstress=True.  New parameter added allowing for
+  additional kwargs to be passed to the underlying scipy.optimize.minimize(). 
+
+Version 1.3.6
+-------------
+
+- **atomman.tools.atomic_info** updated for recently assigned element names
+  and to be more lenient for isotopes.
+
+- **atomman.dump.atom_data** updated to support using kim commands for kim
+  model potentials.
+
+- **atomman.dump.lammps_commands** added - NOT DEBUGGED FOR 
+  NON-CUBIC/ORTHORHOMBIC SYSTEMS!
+
+Version 1.3.5
+-------------
+
+- **atomman.defect.GammaSurface** updates and fixes related to the units
+  parameters for the plotting methods.
+
+- **atomman.defect.SDVPN** bug fixes related to model() generation, loading,
+  and the units parameters for the plotting methods.
+
+- **atomman.Settings** is now a renaming/import of potentials.Settings. 
+
+Version 1.3.4
+-------------
+
+- **atomman.defect.Dislocation** class added that handles the generation of
+  dislocation monopole and periodic array of dislocation atomic configurations
+  in a more user-friendly interface than the previous functions.
+
+- **atomman.region.PlaneSet** class added that allows for a region/shape to be
+  defined using a list of planes.  This allows for the construction of 
+  multi-faceted and/or open-ended shapes.
+
+- **atomman.Box.planes** changed so that the order of the planes returned is
+  consistent with the underlying indices.
+
+- **atomman.build_lammps_potential** inherited from potentials package.
+
+Version 1.3.3
+-------------
+
+- **atomman.Settings** class added that inherits from the corresponding class
+  in the potentials package.  This makes it possible for atomman to access the
+  same local directory of records as the potentials package.
+  
+- **atomman.library** module added that extends the corresponding module from
+  the potentials package to include support for crystal_prototype and 
+  relaxed_crystal records.
+
+- **atomman.load_lammps_potential** added that loads LAMMPS potential
+  information and downloads parameter files from the NIST Interatomic
+  Potentials Repository.
+
+- **atomman.load_prototype** and **atomman.load_crystal** load options added
+  that allow for new Systems to be generated based on crystal_prototype and
+  relaxed_crystal records in the NIST Interatomic Potentials Repository.
+
+- **atomman.defect.GammaSurface** class updated so that the RBF interpolated
+  energies are smoothed across the periodic cell boundaries.
+
+- Fix to keep the code compatible with Python 3.6 (which broke in version
+  1.3.2)
+
+Version 1.3.2
+-------------
+
+- **System.r0** added which finds the shortest interatomic spacing.
+
+- **System.rotate** made more robust.
+
+- **atomman.tools.miller.plane_crystal_to_cartesian** added that identifies
+  the Cartesian normal associated with a crystallographic plane.
+
+- **atomman.lammps.Potential** made consistent with
+  potentials.LAMMPSPotential.  Upcoming versions of atomman will have
+  potentials as a requirement eliminating the duplication: (this class will
+  simply be a renaming of the class from potentials).
+
+- **atomman.lammps.LammpsError** error type added.
+
+- **atomman.defect.dislocation_system_basis** and 
+  **atomman.defect.dislocation_system_transform** functions added supporting
+  the identification of dislocation system orientations based on
+  material-specific parameters.  
+  
+- The "n" parameter in **atomman.defect.free_surface_basis** was renamed to
+  maxindex consistency with the new dislocation_system functions.
+
+- **atomman.defect.VolterraDislocation**, **atomman.defect.Stroh**,
+  **atomman.defect.IsotropicVolterraDislocation**, and
+  **atomman.defect.solve_volterra_dislocation** were updated by integrating in
+  the dislocation_system functions. This makes it possible to now easily define
+  dislocation solutions based on the slip plane, line direction and Burgers
+  vector alone.
+  
+- **atomman.defect.dislocation_periodic_array** was updated to add an old_id
+  parameter to the returned dislocation system making it easier to map the atoms
+  in the defect system back to the perfect crystal base system used during
+  construction.
+  
+- **atomman.defect.FreeSurface** class for generating free surface
+  configurations from a unit cell and (hkl) plane was added.
+
+- **atomman.defect.StackingFault** class completely rebuilt as a subclass of
+  FreeSurface to make it easier to use, i.e. systems can be generated directly
+  from unit cell, (hkl) and shift values.
+
+- **atomman.defect.DifferentialDisplacement** class created. This class offers
+  more plotting options than the old differential_displacement function while
+  dividing the calculation and plotting into separate steps to make it easier
+  to work with.
+
+- **atomman.defect.SDVPN** class updated to allow for VolterraDislocation
+  objects to be directly used as input parameters.  This makes it easier to
+  work with as the transformations between dislocation orientations and gamma
+  surface orientations can be automatically identified and handled.
+  Additionally, solution summary and plotting tools incorporated into the
+  class for convenience.
+
+Version 1.3.1
+-------------
+
+- **Atoms.prop_atype** updated for new atype handling.
+
+- **defect.GammaSurface** default plotting behavior improved.
+
+
+Version 1.3.0
+-------------
+
+- **Support for Python < 3.6 removed.**  Python 2 support removed due to its
+  imminent end at the new year.  Minimal version of 3.6 selected to take
+  advantage of f-strings.
+
+- **Atoms and System natype, atypes** behavior changed to allow for unassigned
+  atype values and/or symbols.  Now, atype values must be > 0 and natypes =
+  max(atype).  CAUTION: this could conceivably break backwards compatibility.
+
+- **lammps.Potential** expanded.
+
+  - **allsymbols** property added to support pair_styles that require all
+    symbols to be listed in the pair_coeff lines even if they are not used.
+  - **status** property added that indicates if the potential is known to
+    have been superseded by a newer version or retracted for being invalid.
+  - **pair_info** now supports an optional masses parameter for overriding
+    default mass values.
+
+- **load.atom_data** now recognizes image flags in the Atoms tables, and reads
+  values from the Masses tables.  Parameter checking is performed allowing for
+  more informative errors to be thrown.
+
+- **dump.atom_data** updated to allow Potential objects to be passed directly,
+  and for pair_info to be included in the generated info LAMMPS input lines.
+
+- **System.masses** attribute added.  This is used for saving mass values from
+  load.atom_data, and for overriding default Potential.masses values in
+  dump.atom_data.
+
+- **defect.dislocation_array** debugged, documented, and made consistent with
+  Volterra solutions.
+
+- **defect.IsotropicVolterraDislocation** displacements fixed and adjusted to
+  predict displacements and stresses consistent with values from defect.Stroh.
+
+- **defect.solve_volterra_dislocation** simplified to remove unnecessary 
+  pre-check of elastic constants.
+
+- **region** submodule added that allows for geometries in space to be defined
+  and used to slice systems and per-atom properties.
+
+- **Box** is now a subclass of region.Shape allowing it to be used for 
+  region-based selection as well.
+
+Version 1.2.8
+-------------
+
+- **defect.GammaSurface** support added for setting shift vectors using
+  Miller-Bravais 4-term vectors.
+
+- **tools.duplicates_allclose** added that identifies unique value sets
+  based on absolute tolerances.
+
+- **load('phonopy'), System.dump('phonopy')** bug fixes.
+
+- **System.atoms_ix** compatibility checks changed and reduced from throwing
+  an error to throwing a warning.
+
+- **Atoms.extend and System.atoms_extend** methods added for adding atoms to
+  existing Atoms/System objects.
+
+Version 1.2.7
+-------------
+
+- **Atoms.model and Box.model** added to create/read data model 
+  representations of the objects.
+
+- **System.composition** added that returns string composition.
+
+- **System.model, load('system_model'), System.dump('system_model')**
+  data model format improved to capture all system information.
+
+- **tools.Miller** functions for converting between Miller and Miller-Bravais
+  crystal planes.
+
+- **defect.GammaSurface** combining of multiple plots better supported.
+
+- **defect.StackingFault** minimum r parameter added allowing all atoms to
+  be at least a certain distance apart.
+
+- **defect.free_surface_basis** added for identifying system orientations
+  associated with free surface configurations.
+
+Version 1.2.6
+-------------
+
+- **lammps.NEBLog** added for nudged elastic band calculation log files.
+
+- **tools.Miller** transformations now all take float values and
+  primitive-conventional cell conversions added.
+
+- **Box.volume** bug fix to ensure returned volume is always positive.
+
+- **defect.StackingFault** stacking fault configuration generator added.
+
+- **nlist, dvect, dmag, defect.slip_vector** routines improved using Cython,
+  alternate implementations of routines removed.
+
+Version 1.2.5
+-------------
+
+- **Box.volume** parameter added.  Also, new class methods for initializing boxes
+  based on crystal systems (cubic, hexagonal, etc.).
+
+- **load('poscar')** now supports excess per-atom lines.
+
+- **System.atoms_ix** added for indexing atoms at the system level.
+
+- **defect.GammaSurface** reworked with improved design and features.
+
+Version 1.2.4
+-------------
+
+- **Atoms.prop_atype()** added to allow properties to be assigned by prop_atype.
+
+- **ElasticConstants.normalized_as()** and **ElasticConstants.is_normal()** added to
+  force/check crystallographic symmetry of elastic tensors.
+
+- **load('atom_data')** updated to support reading files containing # comments.
+
+- **lammps.Potential** now supports specifying potentials with static charges.
+
+- **defect.IsotropicVolterraDislocation** class added as **defect.Stroh** could not calculate
+  isotropic solutions. Both classes are now children of **defect.VolterraDislocation**,
+  and wrapper function **defect.solve_volterra_dislocation()** has been added.
+
+- **defect.dislocation_array()** added that transforms a bulk system into a periodic array of
+  dislocations, where the two system boundaries in the slip plane are periodic, and
+  the third boundary is not.
+
+- **defect.differential_displacement()** updated to provide users more options and control over
+  the plots.
+
+- MANIFEST.in corrected so non-code files should be properly copied during installation.
+
+Version 1.2.3
+-------------
+
+- **load()** updated with more uniform parameters across the different styles.  
+  Style 'phonopy_Atoms' added.
+
+- **System.wrap()** made slightly more robust.
+
+Version 1.2.2
+-------------
+- **System** scale/unscale bug fix.
+
+- **defect.GammaSurface.model()** returned format improved for saving/loading results.
+
+- **load('system_model')** updated with symbols parameter.
+
+Version 1.2.1
+-------------
+
+- Corrections to setup.py for properly loading/building cython code.
+
+Version 1.2.0
+-------------
+
+- Overhaul for Python 2/3 compatibility.
+
+- Reorganization of code and renaming of some features.
+
+- Cython routines added for dvect and neighbor list calculations.
+
+- Improved documentation.

atomman/source/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""
+atomman Project Package Initialization File
+"""

atomman/source/atomman/VERSION

@@ -0,0 +1 @@
+1.5.2

atomman/source/atomman/__init__.py

@@ -0,0 +1,45 @@
+# coding: utf-8
+
+# Standard Python imports
+from importlib import resources
+
+# potentials imports
+from potentials import build_lammps_potential, settings
+
+# atomman imports
+from . import unitconvert
+from . import tools
+from . import thermo
+from . import mep
+from . import region
+from . import lammps
+from .dump import dump, set_dump_styles
+from .dump import __all__ as dump_all
+from .core import *
+from .core import __all__ as core_all
+from . import cluster
+from . import library
+from .library import load_lammps_potential
+from .load import load, FileFormatError
+from .load import __all__ as load_all
+from . import plot
+from . import defect
+
+# Set dump styles
+set_dump_styles()
+
+# Read version from VERSION file
+if hasattr(resources, 'files'):
+    __version__ = resources.files('atomman').joinpath('VERSION').read_text(encoding='UTF-8')
+else:
+    __version__ = resources.read_text('atomman', 'VERSION', encoding='UTF-8').strip()
+
+# Build all list
+__all__ = ['__version__', 'load_lammps_potential', 'build_lammps_potential', 'settings',
+           'tools', 'thermo', 'mep', 'region', 'lammps', 'dump', 'cluster', 'library',
+           'load', 'FileFormatError', 'plot', 'defect']
+__all__ += dump_all + core_all + load_all
+__all__.sort()
+
+# Define default working units
+unitconvert.reset_units(length = 'angstrom', mass = 'amu', energy='eV', charge='e')

atomman/source/atomman/cluster/BondAngleMap.py

@@ -0,0 +1,752 @@
+# coding: utf-8
+
+# Standard Python libraries
+import datetime
+import io
+from typing import Generator, Optional, Union, Tuple
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# https://numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://pandas.pydata.org/
+import pandas as pd
+
+# https://matplotlib.org/
+import matplotlib.pyplot as plt
+
+# atomman imports 
+from .. import Atoms, Box, System
+from ..tools import aslist
+import atomman.unitconvert as uc
+
+class BondAngleMap():
+    """
+    Class for generating and analyzing energies of three atom clusters that
+    explore a range of interatomic distances and bond angles.  Can be used to
+    characterize the 3 atom bond nature of interatomic potentials.
+    """
+    
+    def __init__(self,
+                 model: Union[str, io.IOBase, DM, None] = None,
+                 rmin: Optional[float] = None,
+                 rmax: Optional[float] = None,
+                 rnum: Optional[int] = None,
+                 thetamin: Optional[float] = None,
+                 thetamax: Optional[float] = None,
+                 thetanum: Optional[int] = None,
+                 r_ij: Optional[npt.ArrayLike] = None,
+                 r_ik: Optional[npt.ArrayLike] = None,
+                 theta: Optional[npt.ArrayLike] = None,
+                 energy: Optional[npt.ArrayLike] = None,
+                 symbols: Union[str, list, None] = None):
+        """
+        Class initializer.  The cluster coordinates (r distances and theta
+        angles) are required and can be specified in one of three ways.
+        - A data model containing all the information.
+        - Input ranges (rmin, rmax, rnum, thetamin, thetamax, thetanum).  The r
+          range parameters will be used to generate values for both r_ij and
+          r_ik.
+        - Explicitly giving r_ij, r_ik and theta values.
+
+        Parameters
+        ----------
+        model : str, path-like object or DataModelDict, optional
+            Collected data model results from a series of runs.  Contains both
+            coordinate information and energy values.
+        rmin : float, optional
+            The minimum value used for the r_ij and r_ik spacings.
+        rmax : float, optional
+            The maximum value used for the r_ij and r_ik spacings.
+        rnum : float, optional
+            The number of values used for the r_ij and r_ik spacings.
+        thetamin : float, optional
+            The minimum value used for the theta angles.
+        thetamax : float, optional
+            The maximum value used for the theta angles.
+        thetanum : float, optional
+            The number of values used for the theta angles.
+        r_ij : array-like, optional
+            All r_ij values used.  If given, the lengths of r_ij, r_ik and
+            theta need to be the same.
+        r_ik : array-like, optional
+            All r_ik values used.  If given, the lengths of r_ij, r_ik and
+            theta need to be the same.
+        theta : array-like, optional
+            All theta values used.  If given, the lengths of r_ij, r_ik and
+            theta need to be the same.
+        energy : array-like, optional
+            All measured energies.  If r_ij, r_ik and theta are given then
+            all should be the same length.  If the coordinate range parameters
+            are given, then the energies should be of length rnum*rnum*thetanum
+            and ordered to correspond to three embedded loops with r_ij
+            iterating in the outside loop, r_ik in the middle and theta in the
+            inside.  If energy is not given, then all values will initially be
+            set to np.nan.
+        symbols : str or list, optional
+            Element model symbol(s) to associate with the three atoms if/when
+            systems are created.  Can either be a single symbol to assign to 
+            all atoms, or three symbols to assign to atoms i, j, and k
+            individually.  Not needed if systems are not generated by this
+            class.
+        """
+        self.symbols = symbols
+        if model is not None:
+            try:
+                assert rmin is None and rmax is None and rnum is None
+                assert thetamin is None and thetamax is None and thetanum is None
+                assert r_ij is None and r_ik is None and theta is None
+                assert energy is None
+            except AssertionError as e:
+                raise ValueError('model cannot be given energy or coordinate parameters') from e
+            self.model(model)
+        else:
+            self.set(energy=energy, rmin=rmin, rmax=rmax, rnum=rnum,
+                     thetamin=thetamin, thetamax=thetamax, thetanum=thetanum,
+                     r_ij=r_ij, r_ik=r_ik, theta=theta)
+
+    @property
+    def rmin(self) -> Optional[float]:
+        """float or None: The minimum value used for the r_ij and r_ik spacings."""
+        return self.__rmin
+
+    @property
+    def rmax(self) -> Optional[float]:
+        """float or None: The maximum value used for the r_ij and r_ik spacings."""
+        return self.__rmax
+
+    @property
+    def rnum(self) -> Optional[int]:
+        """int or None: The number of values used for the r_ij and r_ik spacings."""
+        return self.__rnum
+
+    @property
+    def thetamin(self) -> Optional[float]:
+        """float or None: The minimum value used for the theta angles."""
+        return self.__thetamin
+
+    @property
+    def thetamax(self) -> Optional[float]:
+        """float or None: The maximum value used for the theta angles."""
+        return self.__thetamax
+
+    @property
+    def thetanum(self) -> Optional[int]:
+        """int or None: The number of values used for the theta angles."""
+        return self.__thetanum
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """pandas.Dataframe : The cluster coordinates and energies."""
+        return self.__df
+
+    @property
+    def symbols(self) -> Optional[list]:
+        """list or None: the atomic symbols associated with the three atoms"""
+        return self.__symbols
+    
+    @symbols.setter
+    def symbols(self, value: Union[str, list]):
+        
+        if value is not None:
+            value = aslist(value)
+            if len(value) != 1 and len(value) != 3:
+                raise ValueError('Number of symbols must be 1 or 3')
+        
+        self.__symbols = value
+
+    def model(self,
+              model: Union[str, io.IOBase, DM, None] = None,
+              length_unit: str = 'angstrom',
+              energy_unit: str = 'eV') -> Optional[DM]:
+        """
+        Loads or generates a bond angle map data model.
+
+        Note: Generating data models is currently limited to regular values,
+        i.e. ones which the coordinates correspond to embedded loops with
+        r_ij iterating in the outside loop, r_ik in the middle loop and 
+        theta in the inside loop.
+
+        Parameters
+        ----------
+        model : str, file-like object or DataModelDict, optional
+            The data model content or file containing the bond angle map data.
+            If given, the content will be read in and set to the current object.
+            If not given, then a data model will be returned for the object.
+        length_unit : str, optional
+            The unit of length to save the rmin and max values in when
+            generating a data model.  Default is 'angstrom'.
+            value
+        energy_unit : str, optional
+            The unit of energy to save the energy values in when generating a
+            data model.  Default value is 'eV'.
+        
+        Returns
+        -------
+        DataModelDict.DataModelDict
+            The data model containing the bond angle map coordinate information
+            and measured energies.  Only returned if model is not given as a
+            parameter.
+
+        Raises
+        ------
+        ValueError
+            If the data is irregular, i.e. coordinates do not conform to
+            embedded loops with r_ij in the outer loop, r_ik in the middle loop
+            and theta in the inside loop.
+        """
+        # Read in a data model
+        if model is not None:
+            cluster = DM(model).find('bond-angle-map')
+            
+            rmin = uc.value_unit(cluster['minimum-r-spacing'])
+            rmax = uc.value_unit(cluster['maximum-r-spacing'])
+            rnum = int(cluster['number-of-r-spacings'])
+
+            thetamin = float(cluster['minimum-angle'])
+            thetamax = float(cluster['maximum-angle'])
+            thetanum = int(cluster['number-of-angles'])
+
+            energy = uc.value_unit(cluster['energy'])
+
+            self.set(energy=energy, rmin=rmin, rmax=rmax, rnum=rnum, 
+                     thetamin=thetamin, thetamax=thetamax, thetanum=thetanum)
+        
+        else:
+            if self.rnum is None:
+                raise ValueError('model does not support irregular measurements')
+            
+            model = DM()
+            model['bond-angle-map'] = cluster = DM()
+            
+            cluster['minimum-r-spacing'] = uc.model(self.rmin, length_unit)
+            cluster['maximum-r-spacing'] = uc.model(self.rmax, length_unit)
+            cluster['number-of-r-spacings'] = self.rnum
+
+            cluster['minimum-angle'] = self.thetamin
+            cluster['maximum-angle'] = self.thetamax
+            cluster['number-of-angles'] = self.thetanum
+
+            cluster['energy'] = uc.model(self.df.energy, energy_unit)
+
+            return model
+
+    def set(self,
+            rmin: Optional[float] = None,
+            rmax: Optional[float] = None,
+            rnum: Optional[int] = None,
+            thetamin: Optional[float] = None,
+            thetamax: Optional[float] = None,
+            thetanum: Optional[int] = None,
+            r_ij: Optional[npt.ArrayLike] = None,
+            r_ik: Optional[npt.ArrayLike] = None,
+            theta: Optional[npt.ArrayLike] = None,
+            energy: Optional[npt.ArrayLike] = None):
+        """
+        Sets the bond angle coordinates and the associated energies, if given.
+
+        Parameters
+        ----------
+        energy : array-like, optional
+            All measured energies.  If r_ij, r_ik and theta are given then
+            all should be the same length.  If the range parameters are given
+            then the length should be thetanum*rnum*rnum.  If not given, then
+            a new array of nan values will be constructed.
+        rmin : float, optional
+            The minimum value used for the r_ij and r_ik spacings.
+        rmax : float, optional
+            The maximum value used for the r_ij and r_ik spacings.
+        rnum : float, optional
+            The number of values used for the r_ij and r_ik spacings.
+        thetamin : float, optional
+            The minimum value used for the theta angles.
+        thetamax : float, optional
+            The maximum value used for the theta angles.
+        thetanum : float, optional
+            The number of values used for the theta angles.
+        r_ij : array-like, optional
+            All r_ij values used.  If given, the lengths of r_ij, r_ik and
+            theta need to be the same.
+        r_ik : array-like, optional
+            All r_ik values used.  If given, the lengths of r_ij, r_ik and
+            theta need to be the same.
+        theta : array-like, optional
+            All theta values used.  If given, the lengths of r_ij, r_ik and
+            theta need to be the same.
+        energy : array-like, optional
+            All measured energies.  If r_ij, r_ik and theta are given then
+            all should be the same length.  If the coordinate range parameters
+            are given, then the energies should be of length rnum*rnum*thetanum
+            and ordered to correspond to three embedded loops with r_ij
+            iterating in the outside loop, r_ik in the middle and theta in the
+            inside.  If energy is not given, then all values will initially be
+            set to np.nan.
+        """
+
+        # Set coordinate values based on ranges
+        if rmin is not None:
+            if r_ij is not None or r_ik is not None or theta is not None:
+                raise ValueError('range parameters and explicit values cannot be mixed')
+            try:
+                rvals = np.linspace(rmin, rmax, rnum)
+                tvals = np.linspace(thetamin, thetamax, thetanum)
+            except Exception as e:
+                raise ValueError('Invalid range parameters') from e
+
+            # Set range parameters as class properties
+            self.__rmin = rmin
+            self.__rmax = rmax
+            self.__rnum = rnum
+            self.__thetamin = thetamin
+            self.__thetamax = thetamax
+            self.__thetanum = thetanum
+
+            # Generate the input parameters
+            r_ij, r_ik, theta = np.meshgrid(rvals, rvals, tvals, indexing='ij')
+            r_ij = r_ij.flatten()
+            r_ik = r_ik.flatten()
+            theta = theta.flatten()
+
+        # Explicitly set coordinate values
+        else:
+            try:
+                assert rmax is None and rnum is  None
+                assert thetamin is None and thetamax is None and thetanum is None
+            except AssertionError as e:
+                raise ValueError('range parameters and explicit values cannot be mixed') from e
+            try:
+                if len(r_ij) != len(r_ik) or len(r_ij) != len(theta):
+                    raise ValueError('Equal numbers of r_ij, r_ik, and theta values must be given')
+            except Exception as e:
+                raise ValueError('Invalid parameters') from e
+
+            r_ij = np.asarray(r_ij)
+            r_ik = np.asarray(r_ik)
+            theta = np.asarray(theta)
+            
+            # Try to extract range parameters
+            rmin = r_ij.min()
+            rmax = r_ij.max()
+            rnum = len(np.unique(r_ij))
+
+            thetamin = theta.min()
+            thetamax = theta.max()
+            thetanum = len(np.unique(theta))
+
+            try:
+                assert len(r_ij) == thetanum * rnum * rnum
+                rvals = np.linspace(rmin, rmax, rnum)
+                tvals = np.linspace(thetamin, thetamax, thetanum)
+                r_ij_test, r_ik_test, theta_test = np.meshgrid(rvals, rvals, tvals, indexing='ij')
+                assert np.allclose(r_ij, r_ij_test.flatten())
+                assert np.allclose(r_ik, r_ik_test.flatten())
+                assert np.allclose(theta, theta_test.flatten())
+            except:
+                # Set range parameters as None to indicate not correctly ordered
+                self.__rmin = None
+                self.__rmax = None
+                self.__rnum = None
+                self.__thetamin = None
+                self.__thetamax = None
+                self.__thetanum = None
+            else:
+                # Set range parameters
+                self.__rmin = rmin
+                self.__rmax = rmax
+                self.__rnum = rnum
+                self.__thetamin = thetamin
+                self.__thetamax = thetamax
+                self.__thetanum = thetanum
+        
+        # Check energy values
+        if energy is None:
+            energy = np.full(len(r_ij), np.nan)
+        elif len(energy) != len(r_ij):
+            raise ValueError('Mismatch between number of energies given and expected')
+
+        # Compute r_jk values
+        r_jk = np.sqrt(r_ij**2 + r_ik**2 - r_ij * r_ik * 2 * np.cos(np.radians(theta)))
+
+        # Build DataFrame
+        df = {}
+        df['r_ij'] = r_ij
+        df['r_ik'] = r_ik
+        df['r_jk'] = r_jk
+        df['theta'] = theta
+        df['energy'] = energy
+        self.__df = pd.DataFrame(df)
+
+    def itercoords(self) -> Generator[Tuple[float, float, float, float], None, None]:
+        """
+        Iterates through the three-body coordinates, which can be used as inputs for
+        computing energies.
+
+        Yields
+        ------
+        r_ij : float
+            The radial distance between atoms i and j.
+        r_ik : float
+            The radial distance between atoms i and k.
+        r_jk : float
+            The radial distance between atoms j and k.
+        theta : float
+            The angle between i-j and i-k in degrees.
+        """
+        for i in self.df.index:
+            series = self.df.loc[i]
+            yield series.r_ij, series.r_ik, series.r_jk, series.theta
+
+    def itersystem(self,
+                   symbols: Union[str, list, None] = None,
+                   copy: bool = False
+                   ) -> Generator[System, None, None]:
+        """
+        Iterates through the three-body coordinates and returns a System for each.
+        Useful for generating configuration files for simulators.  The atom
+        coordinates will be set such that atom 0 is at [0,0,0], atom 1 at
+        [r_ij,0,0] and atom 2 is in the xy plane based on r_ik and theta.
+
+        Parameters
+        ----------
+        symbols : str or list, optional
+            The element model symbols to assign to the atoms.  Can either be
+            one value for all atoms, or three values for each atom individually.
+            If not given here, will use the values set during class
+            initialization.
+        copy : bool, optional
+            If False (default), then the yielded system is the same object with
+            the coordinates shifted.  If True, each yielded system is a new object.
+
+        Yields
+        ------
+        atomman.System
+            The atomic system containing the three-body cluster.
+        """
+        # Set symbols
+        if symbols is not None:
+            self.symbols = symbols 
+        symbols = self.symbols
+
+        # Identify box bounds based on r_ij values
+        rhi = 3 * self.df.r_ij.max()
+        rlo = - rhi
+        
+        # Identify atypes from symbols
+        if symbols is None or len(symbols) == 1:
+            atype = np.array([1,1,1])
+        elif len(symbols) == 3:
+            symbols, atype = np.unique(symbols, return_inverse=True)
+        else:
+            print(symbols)
+            raise ValueError('Invalid symbols somehow...')
+
+        # Copy = True means generate new system each iteration
+        if copy:
+            for r_ij, r_ik, r_jk, theta in self.itercoords():
+
+                # Build the pos array
+                j_x = r_ij
+                k_x = r_ik * np.cos(np.radians(theta))
+                k_y = r_ik * np.sin(np.radians(theta))
+                pos = np.array([[0.0, 0.0, 0.0],
+                                [j_x, 0.0, 0.0],
+                                [k_x, k_y, 0.0]])
+
+                # Build and yield a new system
+                box = Box(xlo=rlo, xhi=rhi, ylo=rlo, yhi=rhi, zlo=-1.0, zhi=1.0)
+                atoms = Atoms(atype=atype, pos=pos)
+                yield System(atoms=atoms, box=box, symbols=symbols, pbc=[False, False, False])
+
+        # Copy = False means only generate one system and modify pos
+        else:
+            # Build system with all coordinates at [0,0,0]
+            box = Box(xlo=rlo, xhi=rhi, ylo=rlo, yhi=rhi, zlo=-1.0, zhi=1.0)
+            atoms = Atoms(atype=atype, pos=np.zeros([3,3]))
+            system = System(atoms=atoms, box=box, symbols=symbols, pbc=[False, False, False])
+        
+            for r_ij, r_ik, r_jk, theta in self.itercoords():
+                
+                # Modify the three non-zero coordinates
+                system.atoms.pos[1,0] = r_ij
+                system.atoms.pos[2,0] = r_ik * np.cos(np.radians(theta))
+                system.atoms.pos[2,1] = r_ik * np.sin(np.radians(theta))
+
+                yield system
+            
+    def save_table(self,
+                   filename: str,
+                   include_header: bool = True):
+        """
+        Saves a tabulated representation of the coordinates and energy values to a file.
+
+        Parameters
+        ----------
+        filename : str
+            The path to the file where the table will be saved.
+        include_header : bool
+            If True (default) then header comments will be listed at the top of the file.
+        """
+        with open(filename, 'w', encoding='UTF-8') as f:
+
+            if include_header:
+                emin = self.df.energy.min()
+
+                # Create the header comment lines
+                f.write(f'# Comment: this is a file containing an r12, r13, theta - energy-block E(r12, r13, theta) E_min={emin:18.14} eV\n')
+                f.write('# File format: After 9 comment lines (starting with #) there are three lines with (angle in degrees):\n')
+                f.write('# r12_min, r12_max, n_bins_r12; r13_min, r13_max, n_bins_r13, theta_min, theta_max, n_bins_theta followed by\n')
+                f.write('# the data block in the format index_r12, index_r13_ index_theta, E(i_r12,i_r13,i_theta) [eV] one per line.\n')   
+                f.write('# Conversion from index to value: val = val_min + (index-1)*(val_max - val_min)/(n_bins-1)\n')
+                f.write(f'# file created by xxx via code atomman on date {datetime.date.today}\n')
+                #f.write(f'# This is an example for 3-body MD-potential C-W; Reference: J. Jones, CPPC 34, p.123-432 (2019)\n')
+                #f.write(f'# Atom 1: C, Atom 2: W, Atom 3: W\n')
+                #f.write(f'# Version 0.2 (2021-02-15) by U v. Toussaint (IPP)\n')
+                f.write(f'{self.rmin:18.14} {self.rmax:18.14} {self.rnum}\n')
+                f.write(f'{self.rmin:18.14} {self.rmax:18.14} {self.rnum}\n')
+                f.write(f'{self.thetamin:18.14} {self.thetamax:18.14} {self.thetanum}\n')
+
+            l = 0
+            for i in range(self.rnum):
+                for j in range(self.rnum):
+                    for k in range(self.thetanum):
+                        f.write(f'{i+1:6} {j+1:6} {k+1:6} {self.df.energy.values[l]:18.14}\n')
+                        l += 1
+
+    def load_table(self,
+                   filename: str,
+                   length_unit: str = 'angstrom',
+                   energy_unit: str = 'eV'):
+        """
+        Loads a tabulated representation of the coordinates and energy values
+        from a file.
+
+        Parameters
+        ----------
+        filename : str
+            The path to the file where the tabulated data is stored.
+        length_unit : str, optional
+            The units of length used in the file.  Default value is 'angstrom'.
+        energy_unit : str, optional
+            The units of energy used in the file.  Default value is 'eV'.
+        """
+
+        with open(filename, encoding='UTF-8') as f:
+            lines = f.readlines()
+
+        count = 0
+        energies = []
+        i = 1
+        j = 1
+        k = 1
+        for line in lines:
+            terms = line.split()
+            if line.strip()[0] == '#' or len(terms) == 0:
+                continue
+            
+            # Get r_ij min, max, num 
+            if count == 0:
+                rmin = float(terms[0])
+                rmax = float(terms[1])
+                rnum = int(terms[2])
+                count += 1
+            
+            # Check r_ik min, max, num 
+            elif count == 1:
+                assert np.isclose(rmin, float(terms[0])), 'only identical rij and rik ranges currently supported'
+                assert np.isclose(rmax, float(terms[1])), 'only identical rij and rik ranges currently supported'
+                assert np.isclose(rnum, int(terms[2])), 'only identical rij and rik ranges currently supported'
+                count += 1
+
+            # Get theta min, max, num 
+            elif count == 2:
+                thetamin = float(terms[0])
+                thetamax = float(terms[1])
+                thetanum = int(terms[2])
+                count += 1
+                energies = np.empty(rnum*rnum*thetanum)
+            
+            # Get energies
+            else:
+                i = int(terms[0]) - 1
+                j = int(terms[1]) - 1
+                k = int(terms[2]) - 1
+                index = k + j * thetanum + i * rnum * thetanum
+                energies[index] = float(terms[3])
+        
+        # Convert units 
+        rmin = uc.set_in_units(rmin, length_unit)
+        rmax = uc.set_in_units(rmax, length_unit)  
+        energies = uc.set_in_units(energies, energy_unit)
+        
+        self.set(rmin=rmin, rmax=rmax, rnum=rnum, thetamin=thetamin,
+                 thetamax=thetamax, thetanum=thetanum, energy=energies)
+
+    def pdf(self,
+            nbins: int = 301,
+            energymin: float = -15.0,
+            energymax: float = 15.0) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the probability density function for the energy
+        
+        Parameters
+        ----------
+        nbins : int, optional
+            The number of histogram bins to use.  Default value is 301.
+        energymin : float, optional
+            The minimum energy bound to consider.  Default value is -15.0.
+        energymax : float, optional
+            The maximum energy bound to consider.  Default value is 15.0.
+
+        Returns
+        -------
+        pdf : numpy.NDArray
+            The probability density function associated with each bin.
+        centers : numpy.NDArray
+            The center values for each bin.
+        """
+
+        hist, edges = np.histogram(self.df.energy, bins=nbins, range=(energymin, energymax))
+
+        # Divide the historgram count by total number of measurements
+        pdf = hist/len(self.df)
+
+        # Average the bin edges to get the bin centers
+        centers = (edges[:-1] + edges[1:]) / 2
+
+        return pdf, centers
+
+    def cumulative_pdf(self, 
+                       nbins: int = 301,
+                       energymin: float = -15.0,
+                       energymax: float = 15.0) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the cumulative probability density function for the energy.
+        
+        Parameters
+        ----------
+        nbins : int, optional
+            The number of histogram bins to use.  Default value is 301.
+        energymin : float, optional
+            The minimum energy bound to consider.  Default value is -15.0.
+        energymax : float, optional
+            The maximum energy bound to consider.  Default value is 15.0.
+
+        Returns
+        -------
+        cum_pdf : numpy.NDArray
+            The cumulative probability density function associated with each bin.
+        centers : numpy.NDArray
+            The center values for each bin.
+        """
+
+        # Get pdf and centers in the range
+        pdf, centers = self.pdf(nbins=nbins, energymin=energymin, energymax=energymax)
+
+        # Calculate cumulative pdf below energymin
+        shift = np.sum(self.df.energy < energymin) / len(self.df)
+
+        # Calculate the cumulative sum of pdf and apply the shift
+        cum_pdf = np.cumsum(pdf) + shift
+
+        return cum_pdf, centers
+
+    def plot_pdf(self,
+                 nbins: int = 301,
+                 energymin: float = -15.0,
+                 energymax: float = 15.0,
+                 matplotlib_axes: Optional[plt.axes] = None,
+                 **kwargs) -> Optional[plt.figure]:
+        """
+        Generates a plot of the probability density function of the energy.
+
+        Parameters
+        ----------
+        nbins : int, optional
+            The number of histogram bins to use.  Default value is 301.
+        energymin : float, optional
+            The minimum energy bound to consider.  Default value is -15.0.
+        energymax : float, optional
+            The maximum energy bound to consider.  Default value is 15.0.
+        matplotlib_axes : matplotlib.Axes.axes, optional, optional
+            An existing plotting axis to add the pdf plot to.  If not given,
+            a new figure object will be generated.
+        **kwargs : any, optional
+            Any additional key word arguments will be passed to
+            matplotlib.pyplot.figure for generating a new figure object (if
+            axis is not given).
+        
+        Returns
+        -------
+        matplotlib.Figure
+            The generated figure.  Not returned if matplotlib_axes is given.
+        """
+        # Get pdf and centers in the range
+        pdf, centers = self.pdf(nbins=nbins, energymin=energymin, energymax=energymax)
+
+        # Initial plot setup and parameters
+        if matplotlib_axes is None:
+            fig = plt.figure(**kwargs)
+            ax1 = fig.add_subplot(111)
+        else:
+            ax1 = matplotlib_axes
+            
+        ax1.plot(centers, pdf)
+        ax1.set_xlim(energymin, energymax)
+
+        ax1.set_xlabel('Potential Energy [eV]')
+        ax1.set_ylabel('pdf(E)')
+
+        if matplotlib_axes is None:
+            return fig
+
+    def plot_cumulative_pdf(self,
+                            nbins: int = 301,
+                            energymin: float = -15.0,
+                            energymax: float = 15.0,
+                            matplotlib_axes: Optional[plt.axes] = None,
+                            **kwargs) -> Optional[plt.figure]:
+        """
+        Generates a plot of the cumulative probability density function of the energy.
+
+        Parameters
+        ----------
+        nbins : int, optional
+            The number of histogram bins to use.  Default value is 301.
+        energymin : float, optional
+            The minimum energy bound to consider.  Default value is -15.0.
+        energymax : float, optional
+            The maximum energy bound to consider.  Default value is 15.0.
+        matplotlib_axes : matplotlib.Axes.axes, optional, optional
+            An existing plotting axis to add the pdf plot to.  If not given,
+            a new figure object will be generated.
+        **kwargs : any, optional
+            Any additional key word arguments will be passed to
+            matplotlib.pyplot.figure for generating a new figure object (if
+            axis is not given).
+        
+        Returns
+        -------
+        matplotlib.Figure
+            The generated figure.  Not returned if matplotlib_axes is given.
+        """
+        # Get pdf and centers in the range
+        cum_pdf, centers = self.cumulative_pdf(nbins=nbins, energymin=energymin, energymax=energymax)
+
+        # Initial plot setup and parameters
+        if matplotlib_axes is None:
+            fig = plt.figure(**kwargs)
+            ax1 = fig.add_subplot(111)
+        else:
+            ax1 = matplotlib_axes
+            
+        ax1.plot(centers, cum_pdf)
+        ax1.set_xlim(energymin, energymax)
+
+        ax1.set_xlabel('Potential Energy [eV]')
+        ax1.set_ylabel('cumulative pdf(E)')
+
+        if matplotlib_axes is None:
+            return fig

atomman/source/atomman/cluster/__init__.py

@@ -0,0 +1,3 @@
+from .BondAngleMap import BondAngleMap
+
+__all__ = ['BondAngleMap']

atomman/source/atomman/core/Atoms.py

@@ -0,0 +1,572 @@
+# coding: utf-8
+# Standard Python libraries
+from __future__ import annotations
+import io
+from copy import deepcopy
+from collections import OrderedDict
+from typing import Any, Optional, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://pandas.pydata.org/
+import pandas as pd
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# atomman imports
+import atomman.unitconvert as uc
+from ..tools import indexstr
+
+class Atoms(object):
+    """
+    Class for representing a collection of atoms.
+    """
+    
+    class PropertyDict(OrderedDict):
+        """Extends OrderedDict to work with Atoms"""
+        
+        def __init__(self, host: Atoms):
+            """PropertyDict needs to know its host Atoms object."""
+            self.__host = host
+            super(Atoms.PropertyDict, self).__init__()
+        
+        def __setitem__(self, key: str, value: np.ndarray):
+            """
+            Modifies OrderedDict__setitem__() such that
+            1. All values are converted to numpy.ndarrays.
+            2. For new keys, checks are done that data is compatible with host.natoms.
+            3. New keys are also added as attributes to host Atoms object, if allowed.
+            4. For existing keys, new values are saved over the old ones as opposed to
+            only changing the name assignment.
+
+            Parameters
+            ----------
+            key : str
+                The property key name to assign values to.
+            value : numpy.ndarray
+                The values to assign.
+            """
+            # Shortcut to host
+            host = self.__host
+            
+            # Python 2: change to unicode if needed.
+            try:
+                key = key.decode('UTF-8')
+            except:
+                pass
+            
+            # Convert to numpy.ndarray if needed
+            value = np.asarray(value)
+            
+            # Broadcast if needed and allowed
+            if value.shape == ():
+                value = np.array(np.broadcast_to(value, (host.natoms,) + value.shape))
+            elif value.shape[0] == 1:
+                value = np.array(np.broadcast_to(value, (host.natoms,) + value.shape[1:]))
+            elif value.shape[0] != host.natoms:
+                raise ValueError('First dimension of value must be 1 or natoms')
+            
+            # Check that atype values are 1 or greater
+            if key == 'atype' and len(value) > 0 and np.min(value) < 1:
+                raise ValueError('atype values must be >= 1')
+
+            # If key is already assigned, save value over existing values
+            if key in self.keys():
+                self[key][:] = value
+            
+            # Otherwise, set new item and try assigning attribute to host
+            else:
+                super(Atoms.PropertyDict, self).__setitem__(key, value)
+                try:
+                    assert key not in dir(host)
+                    super(Atoms, host).__setattr__(key, value) # pylint: disable=bad-super-call
+                except:
+                    pass
+    
+    def __init__(self,
+                 natoms: Optional[int] = None,
+                 atype: Union[int, npt.ArrayLike, None] = None,
+                 pos: Optional[npt.ArrayLike] = None,
+                 prop: Optional[dict] = None,
+                 model: Union[str, io.IOBase, DM, None] = None, 
+                 safecopy: bool = False,
+                 **kwargs):
+        """
+        Class initializer.
+        
+        Parameters
+        ==========
+        natoms : int, optional
+            The number of atoms.  If not given, will be inferred from other
+            parameters if possible, or set to 1 if not possible.
+        atype : int or list/ndarray of int, optional
+            The integer atomic types to assign to all atoms.  Default is to
+            set all atypes to 1.
+        pos : list/ndarray of float, optional
+            The atomic positions to assign to all atoms.  Default is to set
+            each atom's position to [0,0,0].
+        model : str or DataModelDict, optional
+            File path or content of a JSON/XML data model containing all
+            atom information.  Cannot be given with any other parameters.
+        prop : dict, optional
+            Dictionary containing all per-atom properties.  Can be used
+            instead of atype, pos, and kwargs.  This is for backwards
+            compatibility support with atomman version 1.
+        safecopy : bool, optional
+            Flag indicating if values are to be copied before setting.  For
+            property values given as numpy arrays, direct setting (False,
+            default) may result in the Atoms' property pointing to the original
+            numpy array.  Using safecopy=True deep copies the property values
+            before setting to avoid this.  Note that safecopy=True may be
+            considerably slower for large numbers of atoms and/or properties.
+        kwargs : any
+            All additional key/value pairs are assigned as properties.
+        """
+        
+        # Check for model
+        if model is not None:
+            try:
+                assert natoms is None
+                assert atype is None
+                assert pos is None
+                assert prop is None
+                assert len(kwargs) == 0
+            except:
+                raise ValueError('model cannot be given with any other parameters')
+            
+            # Extract natoms and properties from data model
+            model = DM(model).find('atoms')
+            natoms = model['natoms']
+            prop = OrderedDict()
+            for propmodel in model.aslist('property'):
+                prop[propmodel['name']] = uc.value_unit(propmodel['data'])
+        
+        # Check for prop dictionary
+        if prop is not None:
+            if atype is not None and pos is not None and len(kwargs) > 0:
+                raise ValueError('prop dict cannot be given with keyword properties')
+            
+            # Divide prop into keyword arguments
+            atype = prop.pop('atype', None)
+            pos = prop.pop('pos', None)
+            kwargs = prop
+        
+        # Check atype parameter values
+        if atype is not None:
+            atype = np.asarray(atype)
+            
+            # Handle single atype
+            if atype.ndim == 0:
+                natoms_atype = 1
+            
+            # Handle list of atype
+            elif atype.ndim == 1:
+                natoms_atype = atype.shape[0]
+            else:
+                raise ValueError('Only one atype per atom allowed')
+        else:
+            atype = np.array([1], dtype='uint64')
+            natoms_atype = 1
+        
+        # Check pos parameter values
+        if pos is not None:
+            pos = np.asarray(pos)
+            
+            # Handle single pos
+            if pos.ndim == 1:
+                if pos.shape[0] == 3:
+                    natoms_pos = 1
+                else:
+                    raise ValueError('pos per atom must be 3-dimensional')
+            
+            # Handle list of pos
+            elif pos.ndim == 2:
+                if pos.shape[1] == 3:
+                    natoms_pos = pos.shape[0]
+                else:
+                    raise ValueError('pos per atom must be 3-dimensional')
+            else:
+                raise ValueError('too many dimensions for pos')
+        else:
+            pos = np.zeros((1, 3), dtype='float64')
+            natoms_pos = 1
+        
+        # Check natoms parameter values
+        if natoms is not None:
+            natoms = int(natoms)
+            if ((natoms_atype == 1 or natoms_atype == natoms)
+                and (natoms_pos == 1 or natoms_pos == natoms)):
+                pass
+            else:
+                raise ValueError('natoms and length of atype/pos not compatible')
+        else:
+            if natoms_atype == natoms_pos:
+                natoms = natoms_atype
+            elif natoms_atype == 1:
+                natoms = natoms_pos
+            elif natoms_pos == 1:
+                natoms = natoms_atype
+            else:
+                raise ValueError('lengths of atype and pos not compatible')
+            
+        # Initialize underlying private class attributes
+        super(Atoms, self).__setattr__('_Atoms__natoms', natoms)
+        super(Atoms, self).__setattr__('_Atoms__view', Atoms.PropertyDict(self))
+        super(Atoms, self).__setattr__('_Atoms__dir', deepcopy(dir(self)))
+        
+        # Set properties
+        if safecopy:
+            self.view['atype'] = deepcopy(atype)
+            self.view['pos'] = deepcopy(pos)
+            for key, value in kwargs.items():
+                self.view[key] = deepcopy(value)
+        else:
+            self.view['atype'] = atype
+            self.view['pos'] = pos
+            for key, value in kwargs.items():
+                self.view[key] = value
+    
+    def model(self,
+              prop_name: Optional[list] = None,
+              unit: Optional[list] = None,
+              prop_unit: Optional[dict] = None) -> DM:
+        """
+        Generates a data model for the Atoms object.
+        
+        Parameters
+        ----------
+        prop_name : list, optional
+            The Atoms properties to include.  If neither prop_name nor prop_unit
+            are given, all system properties will be included.
+        unit : list, optional
+            Lists the units for each prop_name as stored in the table.  For a
+            value of None, no conversion will be performed for that property.  
+            If neither unit nor prop_units given, pos will be
+            given in Angstroms and all other values will not be converted.
+        prop_unit : dict, optional
+            dictionary where the keys are the property keys to include, and
+            the values are units to use. If neither unit nor prop_units given, 
+            pos will be given in Angstroms and all other values will not be
+            converted.
+
+        Returns
+        -------
+        DataModelDict.DataModelDict
+            A JSON/XML data model for the current Atoms object.  
+        """
+        
+        # Set prop_unit if needed
+        if prop_unit is None:
+            if prop_name is None:
+                prop_name = self.prop()
+            if unit is None:
+                unit = [None for i in range(len(prop_name))]
+            
+            if len(unit) != len(prop_name):
+                raise ValueError('')
+            prop_unit = {}
+            for p, u  in zip(prop_name, unit):
+                prop_unit[p] = u
+        
+        elif prop_name is not None or unit is not None:
+            raise ValueError('prop_unit cannot be given with prop_name or unit')
+        
+        # Set default pos unit
+        if 'pos' in prop_unit and prop_unit['pos'] is None:
+            prop_unit['pos'] = 'angstrom'
+        
+        # Generate DataModelDict
+        model = DM()
+        model['atoms'] = DM()
+        model['atoms']['natoms'] = self.natoms
+        for prop in prop_unit:
+            unit = prop_unit.get(prop, None)
+            propmodel = DM()
+            propmodel['name'] = prop
+            propmodel['data'] = uc.model(self.prop(prop), unit)
+            model['atoms'].append('property', propmodel)
+        
+        return model
+
+    def __str__(self) -> str:
+        """string output of Atoms data"""
+        atype = self.atype # pylint: disable=no-member
+        pos = self.pos # pylint: disable=no-member
+        lines = ['per-atom properties = ' + str(self.prop())]
+        lines.append('     id |   atype |  pos[0] |  pos[1] |  pos[2]')
+        for i in range(self.natoms):
+            lines.append('%7i | %7i | %7.3f | %7.3f | %7.3f' % (i, atype[i], pos[i,0], pos[i,1], pos[i,2]))
+        
+        return '\n'.join(lines)
+    
+    def __setattr__(self, name: str, value: Any):
+        """Control setting of user-defined attributes"""
+        if not hasattr(self, name) or name in self.view:
+            self.view[name] = value
+        else:
+            super(Atoms, self).__setattr__(name, value)
+    
+    def __intslice(self, intnum):
+        if intnum == -1:
+            return slice(intnum, None)
+        else:
+            return slice(intnum, intnum+1)
+    
+    def __deepcopy__(self, memo) -> Atoms:
+        """Properly handle deepcopy"""
+        d = OrderedDict()
+        atype = deepcopy(self.view['atype'])
+        pos = deepcopy(self.view['pos'])
+        for key in self.view:
+            if key not in ['atype', 'pos']:
+                d[key] = deepcopy(self.view[key])
+        return Atoms(atype=atype, pos=pos, **d)
+    
+    def __getitem__(self, index) -> Atoms:
+        """Index getting of Atoms."""
+        view = OrderedDict()
+        if isinstance(index, (int, np.integer)):
+            index = self.__intslice(index)
+        for key in self.view.keys():
+            view[key] = self.view[key][index]
+        return Atoms(**view)
+        
+    def __setitem__(self, index, value):
+        """Index setting of Atoms."""
+        try:
+            assert isinstance(value, Atoms)
+            assert sorted(value.view.keys()) == sorted(self.view.keys())
+        except:
+            raise ValueError('Can only set Atoms with matching properties')
+        
+        if isinstance(index, (int, np.integer)):
+            index = self.__intslice(index)
+            
+        for key in self.view.keys():
+            self.view[key][index] = value.view[key]
+    
+    def __len__(self) -> int:
+        """len of atoms = natoms."""
+        return self.natoms
+    
+    @property
+    def natoms(self) -> int:
+        """int : The number of atoms in the Atoms class."""
+        return self.__natoms 
+    
+    @property
+    def atypes(self) -> tuple:
+        """tuple : List of int atom types."""
+        return tuple(range(1, self.natypes+1))
+    
+    @property
+    def natypes(self) -> int:
+        """int : The number of atom types in the Atoms class."""
+        if np.min(self.atype) < 1: 
+            raise ValueError('atype values < 1 not allowed')
+
+        return int(np.max(self.atype)) 
+        
+    @property
+    def view(self) -> PropertyDict:
+        """PropertyDict : All assigned per-atom properties."""
+        return self.__view 
+    
+    def prop(self,
+             key: Optional[str] = None,
+             index: Union[int, list, slice, None] = None,
+             value: Optional[Any] = None,
+             a_id: Optional[int] = None
+             ) -> Union[list, Atoms, np.ndarray, None]:
+        """
+        Accesses the per-atom properties for controlled getting and setting.
+        For getting values, prop() always returns a copy of the underlying
+        data as opposed to the data itself.
+        
+        Parameters
+        ----------
+        key : str, optional
+            Per-atom property name.
+        index : int, list, slice, optional
+            Index of atoms.
+        value : any, optional
+            Property values to assign.
+        a_id : int, optional
+            Integer atom index.  Left in for backwards compatibility.
+        
+        Returns
+        -------
+        list
+            If no parameters given, returns a list of all assigned property
+            keys.
+        atomman.Atoms
+            If index or a_id is given without value or key, returns a new
+            Atoms instance for the specified atom indices.
+        numpy.ndarray
+            If key (and index/a_id) is given without value, returns a copy of
+            the data associated with that property key.
+        
+        raises
+        ------
+        ValueError
+            If a_id and index are both given, or only value is given.
+        """
+        
+        # Handle a_id
+        if a_id is not None:
+            if index is not None:
+                raise ValueError('a_id and index cannot both be given')
+            index = a_id
+        
+        # Get values if value is None
+        if value is None:
+            if key is None:
+                # Return list of property names when no parameters are given
+                if index is None:
+                    return list(self.view.keys())
+                # Return copy of slice if only index is given
+                else:
+                    return deepcopy(self[index])
+            # If key is given, return copy of property values
+            else:
+                if index is None:
+                    return deepcopy(self.view[key])
+                else:
+                    return deepcopy(self.view[key][index])
+        
+        # Set values if value is given
+        else:
+            # If no key, set value to atoms (or a slice)
+            if key is None:
+                if not isinstance(value, Atoms):
+                    raise TypeError('If key is None, value must be instance of atomman.Atoms')
+                if index is None:
+                    self[:] = value
+                else:
+                    self[index] = value
+            
+            # If key is given, set copy of value to property
+            else:
+                if index is None:
+                    self.view[key] = deepcopy(value)
+                else:
+                    self.view[key][index] = value
+    
+    def prop_atype(self,
+                   key: str,
+                   value: Any,
+                   atype: Optional[int] = None):
+        """
+        Allows for per-atom properties to be assigned according to
+        Atoms.atypes.
+
+        Parameters
+        ----------
+        key : str
+            Per-atom property name.
+        value : list, any
+            Property value(s) to assign.  If atype is not given, this should be
+            an object of length Atoms.natypes. Otherwise, should be a single per-atom
+            value.
+        atype : int, optional
+            A specific atype to assign value to.
+
+        Raises
+        ------
+        ValueError
+            If length of value does not match Atoms.natypes or atype is not in
+            Atoms.atypes.
+        """
+
+        # Set values across all atype values
+        if atype is None:
+            value = np.asarray(value)
+            if len(value) >= self.natypes:
+                self.view[key] = value[self.atype - 1] # pylint: disable=no-member
+            else:
+                raise ValueError('length of value less than natypes')
+        
+        # Set values for only one atype
+        else:
+            if atype in self.atypes:
+                if key not in self.prop():
+                    self.view[key] = np.zeros_like(value)
+                self.view[key][self.atype==atype] = value # pylint: disable=no-member
+            else:
+                raise ValueError('atype not found')
+    
+    def df(self) -> pd.DataFrame:
+        """
+        Returns a pandas.DataFrame of all atomic properties.  Multi-dimensional
+        per-atom data will be converted into multiple table columns.
+        """
+        
+        # Initialize new dictionary of values
+        values = OrderedDict()
+        for key in self.view.keys():
+            
+            # Flatten multidimensional arrays
+            for index, istr in indexstr(self.view[key].shape[1:]):
+                newkey = key + istr
+                
+                # Copy values over
+                if index == ():
+                    values[newkey] = self.view[key]
+                else:
+                    values[newkey] = self.view[key][(Ellipsis, ) + index]
+        
+        # Return DataFrame
+        return pd.DataFrame(values)
+    
+    def extend(self, value: Union[Atoms, int]) -> Atoms:
+        """
+        Allows additional atoms to be added to the end of the atoms list.
+        
+        Parameters
+        ----------
+        value : atomman.Atoms or int
+            An int value will result in the atoms object being extended by
+            that number of atoms, with all per-atom properties having default
+            values (atype = 1, everything else = 0).  For an Atoms value, the
+            current atoms list will be extended by the correct number of atoms
+            and all per-atom properties in value will be copied over.  Any
+            properties defined in one Atoms object and not the other will be
+            set to default values.
+        
+        Returns
+        -------
+        atomman.Atoms
+            A new Atoms object containing all atoms and properties of the
+            current object plus the additional atoms.
+        """
+        
+        # Handle different value types
+        if isinstance(value, (int, np.integer)):
+            natoms = value
+            atoms = Atoms(natoms=natoms)
+        elif isinstance(value, Atoms):
+            natoms = value.natoms
+            atoms = value        
+        else:
+            raise TypeError('can only add Atoms or an int # of atoms')
+        
+        # Generate newatoms by copying values of self + natoms extras
+        index = list(range(self.natoms)) + [0 for i in range(natoms)]
+        newatoms = self[index]
+        
+        # Create empty values for atoms.props not in newatoms (self)
+        for prop in atoms.prop():
+            if prop not in newatoms.prop():
+                newatoms.view[prop] = np.zeros((newatoms.natoms, ) + atoms.view[prop][0].shape, dtype=atoms.view[prop][0].dtype)
+        
+        # Copy values to the extra atoms in newatoms
+        for prop in newatoms.prop():
+            if prop in atoms.prop():
+                newatoms.view[prop][self.natoms:] = atoms.view[prop]
+            else:
+                newatoms.view[prop][self.natoms:] = np.zeros((natoms, ) + self.view[prop][0].shape, dtype=self.view[prop][0].dtype)
+        
+        return newatoms

atomman/source/atomman/core/Box.py

@@ -0,0 +1,1112 @@
+# coding: utf-8
+
+# Standard Python libraries
+from __future__ import annotations
+from copy import deepcopy
+import io
+from typing import Any, Optional, Union, Tuple
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# local imports
+import atomman.unitconvert as uc
+from ..tools import vect_angle, miller
+from ..region import Shape, Plane
+
+class Box(Shape, object):
+    """
+    A representation of a triclinic (parallelepiped) box.
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initializes a Box.  If parameters besides origin are given they
+        must completely define the box.  Allowed parameter sets are:
+
+        - no parameters -> box is set to square unit box with origin = [0,0,0].
+
+        - origin. -> Only origin is changed (same as setting origin directly).
+
+        - vects, (and origin).
+
+        - avect, bvect, cvect, (and origin).
+
+        - a, b, c, (alpha, beta, gamma, and origin).
+
+        - lx, ly, lz, (xy, xz, yz, and origin).
+
+        - xlo, xhi, ylo, yhi, zlo, zhi, (xy, xz, and yz).
+
+        - model
+
+        See the description of class methods and attributes for more details
+        on the allowed parameters.
+
+        """
+        self.__vects = np.eye(3, dtype='float64')
+        self.__origin = np.zeros(3, dtype='float64')
+        self.__reciprocal_vects = None
+
+        if len(kwargs) > 0:
+            if 'model' in kwargs:
+                if len(kwargs) > 1:
+                    raise ValueError('model cannot be given with other parameters')
+                self.model(kwargs['model'])
+            else:
+                self.set(**kwargs)
+
+    @classmethod
+    def cubic(cls, a: float) -> Box:
+        """
+        Initializes a Box in standard cubic setting using only cubic lattice
+        parameters.
+
+        a = b = c, alpha = beta = gamma = 90
+
+        Parameters
+        ----------
+        - a : float
+            The a lattice constant
+
+        Returns
+        -------
+        atomman.Box
+        """
+        return cls(a=a, b=a, c=a, alpha=90, beta=90, gamma=90)
+
+    @classmethod
+    def hexagonal(cls, a: float, c: float) -> Box:
+        """
+        Initializes a Box in standard hexagonal setting using only hexagonal lattice
+        parameters.
+
+        a = b != c, alpha = beta = 90, gamma = 120
+
+        Parameters
+        ----------
+        - a : float
+            The a lattice constant
+        - c : float
+            The c lattice constant
+
+        Returns
+        -------
+        atomman.Box
+        """
+        if a == c:
+            raise ValueError('hexagonal lattice constants must be different')
+
+        return cls(a=a, b=a, c=c, alpha=90, beta=90, gamma=120)
+
+    @classmethod
+    def tetragonal(cls, a: float, c: float) -> Box:
+        """
+        Initializes a Box in standard tetragonal setting using only tetragonal lattice
+        parameters.
+
+        a = b != c, alpha = beta = gamma = 90
+
+        Parameters
+        ----------
+        - a : float
+            The a lattice constant
+        - c : float
+            The c lattice constant
+
+        Returns
+        -------
+        atomman.Box
+        """
+        if a == c:
+            raise ValueError('tetragonal lattice constants must be different')
+
+        return cls(a=a, b=a, c=c, alpha=90, beta=90, gamma=90)
+
+    @classmethod
+    def trigonal(cls, a: float, alpha: float) -> Box:
+        """
+        Initializes a Box in standard trigonal setting using only trigonal lattice
+        parameters.
+
+        a = b = c, alpha = beta = gamma < 120
+
+        Parameters
+        ----------
+        - a : float
+            The a lattice constant
+        - alpha : float
+            The alpha lattice angle in degrees
+
+        Returns
+        -------
+        atomman.Box
+        """
+        if alpha >= 120.0:
+            raise ValueError('trigonal alpha angle must be less than 120 degrees')
+
+        return cls(a=a, b=a, c=a, alpha=alpha, beta=alpha, gamma=alpha)
+
+    @classmethod
+    def orthorhombic(cls, a: float, b: float, c: float) -> Box:
+        """
+        Initializes a Box in standard orthorhombic setting using only orthorhombic lattice
+        parameters.
+
+        a != b != c, alpha = beta = gamma = 90
+
+        Parameters
+        ----------
+        - a : float
+            The a lattice constant
+        - b : float
+            The b lattice constant
+        - c : float
+            The c lattice constant
+
+        Returns
+        -------
+        atomman.Box
+        """
+        if a == b or a == c:
+            raise ValueError('orthorhombic lattice constants must be different')
+
+        return cls(a=a, b=b, c=c, alpha=90, beta=90, gamma=90)
+
+    @classmethod
+    def monoclinic(cls, a: float, b: float, c: float, beta: float) -> Box:
+        """
+        Initializes a Box in standard monoclinic setting using only monoclinic lattice
+        parameters.
+
+        a != b != c, alpha = gamma = 90, beta > 90
+
+        Parameters
+        ----------
+        - a : float
+            The a lattice constant
+        - b : float
+            The b lattice constant
+        - c : float
+            The c lattice constant
+        - beta : float
+            The beta lattice angle in degrees
+
+        Returns
+        -------
+        atomman.Box
+        """
+        if a == b or a == c:
+            raise ValueError('monoclinic lattice constants must be different')
+        if beta <= 90.0:
+            raise ValueError('monoclinic angle beta must be greater than 90 degrees')
+
+        return cls(a=a, b=b, c=c, alpha=90, beta=beta, gamma=90)
+
+    @classmethod
+    def triclinic(cls, a: float, b: float, c: float,
+                  alpha: float, beta: float, gamma: float) -> Box:
+        """
+        Initializes a Box in standard triclinic setting using only triclinic lattice
+        parameters.
+
+        a != b != c, alpha != beta != gamma
+
+        Parameters
+        ----------
+        - a : float
+            The a lattice constant
+        - b : float
+            The b lattice constant
+        - c : float
+            The c lattice constant
+        - alpha : float
+            The alpha lattice angle in degrees
+        - beta : float
+            The beta lattice angle in degrees
+        - gamma : float
+            The gamma lattice angle in degrees
+
+        Returns
+        -------
+        atomman.Box
+        """
+        if a == b or a == c:
+            raise ValueError('monoclinic lattice constants must be different')
+        if alpha == beta or alpha == gamma:
+            raise ValueError('monoclinic lattice angles must be different')
+
+        return cls(a=a, b=b, c=c, alpha=alpha, beta=beta, gamma=gamma)
+
+    @property
+    def vects(self) -> np.ndarray:
+        """numpy.ndarray : Array containing all three box vectors.  Can be set directly."""
+        return deepcopy(self.__vects)
+
+    @vects.setter
+    def vects(self, value: npt.ArrayLike):
+        self.__vects[:] = value
+
+        # Zero out near zero terms
+        self.__vects[np.isclose(self.__vects/abs(self.__vects).max(), 0.0, atol=1e-9)] = 0.0
+
+        # Reset reciprocal_vects
+        self.__reciprocal_vects = None
+
+    @property
+    def reciprocal_vects(self) -> np.ndarray:
+        """
+        numpy.ndarray : Array of the crystallographic reciprocal box vectors.
+        These have not been scaled by the factor of 2 pi.
+        """
+        if self.__reciprocal_vects is None:
+            self.__reciprocal_vects = np.linalg.inv(self.vects).T
+        
+        return self.__reciprocal_vects
+
+    @property
+    def origin(self) -> np.ndarray:
+        """numpy.ndarray : Box origin position where vects are added to define the box.  Can be set directly."""
+        return deepcopy(self.__origin)
+
+    @origin.setter
+    def origin(self, value: npt.ArrayLike):
+        self.__origin[:] = value
+
+    @property
+    def avect(self) -> np.ndarray:
+        """numpy.ndarray : Vector associated with the a box dimension."""
+        return self.vects[0]
+
+    @property
+    def bvect(self) -> np.ndarray:
+        """numpy.ndarray : Vector associated with the b box dimension."""
+        return self.vects[1]
+
+    @property
+    def cvect(self) -> np.ndarray:
+        """numpy.ndarray : Vector associated with the c box dimension."""
+        return self.vects[2]
+
+    @property
+    def a(self) -> float:
+        """float : The a lattice parameter (magnitude of avect)."""
+        return (self.__vects[0,0]**2 + self.__vects[0,1]**2 + self.__vects[0,2]**2)**0.5
+
+    @property
+    def b(self) -> float:
+        """float : The b lattice parameter (magnitude of avect)."""
+        return (self.__vects[1,0]**2 + self.__vects[1,1]**2 + self.__vects[1,2]**2)**0.5
+
+    @property
+    def c(self) -> float:
+        """float : The c lattice parameter (magnitude of avect)."""
+        return (self.__vects[2,0]**2 + self.__vects[2,1]**2 + self.__vects[2,2]**2)**0.5
+
+    @property
+    def alpha(self) -> float:
+        """float : The alpha lattice angle in degrees (angle between bvect and cvect)."""
+        return vect_angle(self.__vects[1], self.__vects[2])
+
+    @property
+    def beta(self) -> float:
+        """float : The beta lattice angle in degrees (angle between avect and cvect)."""
+        return vect_angle(self.__vects[0], self.__vects[2])
+
+    @property
+    def gamma(self) -> float:
+        """float : The gamma lattice angle in degrees (angle between avect and bvect)."""
+        return vect_angle(self.__vects[0], self.__vects[1])
+
+    @property
+    def lx(self) -> float:
+        """float : LAMMPS lx box length (avect[0] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__vects[0,0]
+
+    @property
+    def ly(self) -> float:
+        """float : LAMMPS ly box length (bvect[1] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__vects[1,1]
+
+    @property
+    def lz(self) -> float:
+        """float : LAMMPS lz box length (cvect[2] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__vects[2,2]
+
+    @property
+    def xy(self) -> float:
+        """float : LAMMPS xy box tilt factor (bvect[0] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__vects[1,0]
+
+    @property
+    def xz(self) -> float:
+        """float : LAMMPS xz box tilt factor (cvect[0] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__vects[2,0]
+
+    @property
+    def yz(self) -> float:
+        """float : LAMMPS yz box tilt factor (cvect[1] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__vects[2,1]
+
+    @property
+    def xlo(self) -> float:
+        """float : LAMMPS xlo box lo term (origin[0] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__origin[0]
+
+    @property
+    def ylo(self) -> float:
+        """float : LAMMPS ylo box lo term (origin[1] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__origin[1]
+
+    @property
+    def zlo(self) -> float:
+        """float : LAMMPS zlo box lo term (origin[2] for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__origin[2]
+
+    @property
+    def xhi(self) -> float:
+        """float : LAMMPS xhi box hi term (origin[0] + lx for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__origin[0] + self.__vects[0,0]
+
+    @property
+    def yhi(self) -> float:
+        """float : LAMMPS yhi box hi term (origin[1] + ly for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__origin[1] + self.__vects[1,1]
+
+    @property
+    def zhi(self) -> float:
+        """float : LAMMPS zhi box hi term (origin[2] + lz for normalized boxes)."""
+        assert self.is_lammps_norm(), 'Box is not normalized for LAMMPS style parameters'
+        return self.__origin[2] + self.__vects[2,2]
+
+    @property
+    def volume(self) -> float:
+        """float : The volume of the box."""
+        return np.abs(np.dot(self.avect, np.cross(self.bvect, self.cvect)))
+
+    @property
+    def planes(self) -> Tuple[Plane]:
+        """tuple : The box's planes represented as atomman.region.Plane objects."""
+        return (Plane(np.cross(self.cvect, self.bvect), self.origin),
+                Plane(np.cross(self.avect, self.cvect), self.origin),
+                Plane(np.cross(self.bvect, self.avect), self.origin),
+                Plane(np.cross(self.bvect, self.cvect), self.origin + self.avect),
+                Plane(np.cross(self.cvect, self.avect), self.origin + self.bvect),
+                Plane(np.cross(self.avect, self.bvect), self.origin + self.cvect))
+
+    def __str__(self) -> str:
+        """
+        The string representation of the box.  Lists the three vectors and origin.
+        """
+        return '\n'.join(['avect =  [%6.3f, %6.3f, %6.3f]' % (self.__vects[0,0], self.__vects[0,1], self.__vects[0,2]),
+                          'bvect =  [%6.3f, %6.3f, %6.3f]' % (self.__vects[1,0], self.__vects[1,1], self.__vects[1,2]),
+                          'cvect =  [%6.3f, %6.3f, %6.3f]' % (self.__vects[2,0], self.__vects[2,1], self.__vects[2,2]),
+                          'origin = [%6.3f, %6.3f, %6.3f]' % (self.__origin[0],  self.__origin[1],  self.__origin[2])])
+
+    def model(self,
+              model: Union[str, io.IOBase, DM, None] = None,
+              length_unit: str = 'angstrom'
+              ) -> Optional[DM]:
+        """
+        Reads or generates a data model for the box.
+
+        Parameters
+        ----------
+        model : str or DataModelDict, optional
+            JSON/XML formatted data, or path to file containing said data.  If
+            not given, then a model for the current box will be returned.
+        length_unit : str, optional
+            Unit of length to save box values in if data model is to be
+            generated.  Default value is 'angstrom'.
+
+        Returns
+        -------
+        DataModelDict.DataModelDict
+            A JSON/XML equivalent data model for the box.  Returned if model
+            is not given
+        """
+        # Set values if model given
+        if model is not None:
+
+            # Find box element
+            model = DM(model).find('box')
+            avect = uc.value_unit(model['avect'])
+            bvect = uc.value_unit(model['bvect'])
+            cvect = uc.value_unit(model['cvect'])
+            origin = uc.value_unit(model['origin'])
+            self.set(avect=avect, bvect=bvect, cvect=cvect, origin=origin)
+
+        # Return DataModelDict if model not given
+        else:
+            model = DM()
+            model['box'] = DM()
+            model['box']['avect'] = uc.model(self.avect, length_unit)
+            model['box']['bvect'] = uc.model(self.bvect, length_unit)
+            model['box']['cvect'] = uc.model(self.cvect, length_unit)
+            model['box']['origin']= uc.model(self.origin, length_unit)
+
+            return model
+
+    def set(self, **kwargs):
+        """
+        Sets a Box's dimensions.  If parameters besides origin are given they
+        must completely define the box.  Allowed parameter sets are:
+
+        - no parameters -> box is set to square unit box with origin = [0,0,0].
+
+        - origin. -> Only origin is changed (same as setting origin directly).
+
+        - vects, (and origin).
+
+        - avect, bvect, cvect, (and origin).
+
+        - a, b, c, (alpha, beta, gamma, and origin).
+
+        - lx, ly, lz, (xy, xz, yz, and origin).
+
+        - xlo, xhi, ylo, yhi, zlo, zhi, (xy, xz, and yz).
+
+        See the description of class methods and attributes for more details
+        on the allowed parameters.
+        """
+
+        # Set default values if no kwargs given
+        if len(kwargs) == 0:
+            self.vects = np.eye(3)
+            self.origin = np.zeros(3)
+
+        # Set directly if vects given
+        elif 'vects' in kwargs:
+            vects = kwargs.pop('vects')
+            origin = kwargs.pop('origin', [0.0, 0.0, 0.0])
+            assert len(kwargs) == 0, 'Invalid arguments'
+            self.vects = vects
+            self.origin = origin
+
+        # Call set_vectors if vect inputs given
+        elif 'avect' in kwargs:
+            self.set_vectors(**kwargs)
+
+        # Call set_lengths if length inputs given
+        elif 'lx' in kwargs:
+            self.set_lengths(**kwargs)
+
+        # Call set_hi_los if hi/lo inputs given
+        elif 'xlo' in kwargs:
+            self.set_hi_los(**kwargs)
+
+        # Call set_abc if vector magnitudes are given
+        elif 'a' in kwargs:
+            self.set_abc(**kwargs)
+
+        # Set only origin if given alone
+        elif 'origin' in kwargs:
+            origin = kwargs.pop('origin')
+            assert len(kwargs) == 0, 'Invalid arguments'
+            self.origin = origin
+
+        else:
+            raise TypeError('Invalid arguments')
+
+    def set_vectors(self,
+                    avect: npt.ArrayLike,
+                    bvect: npt.ArrayLike,
+                    cvect: npt.ArrayLike,
+                    origin: Optional[npt.ArrayLike] = None):
+        """
+        Set the box using the three box vectors.
+
+        Parameters
+        ----------
+        avect : array-like object
+            The 3D vector for the a box dimension.
+        bvect : array-like object
+            The 3D vector for the b box dimension.
+        cvect : array-like object
+            The 3D vector for the c box dimension.
+        origin : array-like object, optional
+            The 3D vector for the box origin position.  Default value is
+            (0,0,0).
+        """
+        # Set default origin
+        if origin is None:
+            origin = [0.0, 0.0, 0.0]
+
+        # Combine avect, bvect and cvect into vects and set directly
+        self.vects = [avect, bvect, cvect]
+        self.origin = origin
+
+    def set_abc(self,
+                a: float, b: float, c: float,
+                alpha: float = 90.0,
+                beta: float = 90.0,
+                gamma: float = 90.0,
+                origin: Optional[npt.ArrayLike] = None):
+        """
+        Set the box using crystal cell lattice parameters and angles.
+
+        Parameters
+        ----------
+        a : float
+            The a lattice parameter.
+        b : float
+            The b lattice parameter.
+        c : float
+            The c lattice parameter.
+        alpha : float, optional
+            The alpha lattice angle in degrees (angle between b and c vectors).
+            Default value is 90.0.
+        beta : float, optional
+            The beta lattice angle in degrees (angle between a and c vectors).
+            Default value is 90.0.
+        gamma : float, optional
+            The gamma lattice angle in degrees (angle between a and b vectors).
+            Default value is 90.0.
+        origin : array-like object, optional
+            The 3D vector for the box origin position.  Default value is
+            (0,0,0).
+        """
+        # Check that angles are between 0 and 180
+        if alpha <= 0 or alpha >=180 or beta <= 0 or beta >= 180 or gamma <=0 or gamma >=180:
+            raise ValueError('lattice angles must be between 0 and 180 degrees')
+
+        # Convert to lx, ly, lz, xy, xz, yz
+        lx = a
+        xy = b * np.cos(gamma * np.pi / 180)
+        xz = c * np.cos(beta * np.pi / 180)
+        ly = (b**2 - xy**2)**0.5
+        yz = (b * c * np.cos(alpha * np.pi / 180) - xy * xz) / ly
+        lz = (c**2 - xz**2 - yz**2)**0.5
+
+        # Call set_lengths
+        self.set_lengths(lx=lx, ly=ly, lz=lz, xy=xy, xz=xz, yz=yz, origin=origin)
+
+    def set_lengths(self,
+                    lx: float, ly: float, lz: float,
+                    xy: float = 0.0, xz: float = 0.0, yz: float = 0.0,
+                    origin: Optional[npt.ArrayLike] = None):
+        """
+        Set the box using LAMMPS box lengths and tilt factors.
+
+        Parameters
+        ----------
+        lx : float
+            The LAMMPS box length in the x direction.
+        ly : float
+            The LAMMPS box length in the y direction.
+        lz : float
+            The LAMMPS box length in the z direction.
+        xy : float, optional
+            The LAMMPS box tilt factor in the xy direction.  Default value is
+            0.0.
+        xz : float, optional
+            The LAMMPS box tilt factor in the xz direction.  Default value is
+            0.0.
+        yz : float, optional
+            The LAMMPS box tilt factor in the yz direction.  Default value is
+            0.0.
+        origin : array-like object, optional
+            The 3D vector for the box origin position.  Default value is
+            (0,0,0).
+        """
+
+        assert lx > 0 and ly > 0 and lz > 0, 'box lengths must be positive'
+
+        # Set default origin
+        if origin is None:
+            origin = [0.0, 0.0, 0.0]
+
+        # Construct vects array
+        self.vects = [[lx, 0.0, 0.0],
+                      [xy, ly,  0.0],
+                      [xz, yz,  lz]]
+        self.origin = origin
+
+    def set_hi_los(self,
+                   xlo: float, xhi: float,
+                   ylo: float, yhi: float,
+                   zlo: float, zhi: float,
+                   xy: float = 0.0, xz: float = 0.0, yz: float = 0.0):
+        """
+        Set the box using LAMMPS box hi's, lo's and tilt factors.
+
+        Parameters
+        ----------
+        xlo : float
+            The LAMMPS xlo box lo term.
+        xhi : float
+            The LAMMPS xhi box hi term.
+        ylo : float
+            The LAMMPS ylo box lo term.
+        yhi : float
+            The LAMMPS yhi box hi term.
+        zlo : float
+            The LAMMPS zlo box lo term.
+        zhi : float
+            The LAMMPS zhi box hi term.
+        xy : float, optional
+            The LAMMPS box tilt factor in the xy direction.  Default value is
+            0.0.
+        xz : float, optional
+            The LAMMPS box tilt factor in the xz direction.  Default value is
+            0.0.
+        yz : float, optional
+            The LAMMPS box tilt factor in the yz direction.  Default value is
+            0.0.
+        """
+
+        # Convert to hi and lo term to lengths and origin
+        lx = xhi - xlo
+        ly = yhi - ylo
+        lz = zhi - zlo
+        origin = [xlo, ylo, zlo]
+
+        # Call set_lengths
+        self.set_lengths(lx=lx, ly=ly, lz=lz, xy=xy, xz=xz, yz=yz, origin=origin)
+
+    def is_lammps_norm(self) -> bool:
+        """
+        Tests if box is compatible with LAMMPS.
+        Note: large box tilt factors not checked.  The LAMMPS command
+        'box tilt large' may be needed to run LAMMPS.
+        """
+        return (self.__vects[0,1] == 0.0
+            and self.__vects[0,2] == 0.0
+            and self.__vects[1,2] == 0.0
+            and self.__vects[0,0] > 0.0
+            and self.__vects[1,1] > 0.0
+            and self.__vects[2,2] > 0.0)
+
+    def inside(self,
+               pos: npt.ArrayLike,
+               inclusive: bool = True) -> np.ndarray:
+        """
+        Indicates if position(s) are inside the shape.
+        
+        Parameters
+        ----------
+        pos : array-like object
+            Nx3 array of coordinates. 
+        inclusive : bool, optional
+            Indicates if points on the shape's boundaries are to be included.
+            Default value is True.
+        
+        Returns
+        -------
+        numpy.NDArray
+            N array of bool values: True if inside shape
+        """
+        # Retrieve the Box's planes
+        planes = self.planes
+
+        # Find all points below each plane, i.e. inside the box
+        return ( planes[0].below(pos, inclusive=inclusive)
+               & planes[1].below(pos, inclusive=inclusive)
+               & planes[2].below(pos, inclusive=inclusive)
+               & planes[3].below(pos, inclusive=inclusive)
+               & planes[4].below(pos, inclusive=inclusive)
+               & planes[5].below(pos, inclusive=inclusive))
+
+    def vector_crystal_to_cartesian(self, indices: npt.ArrayLike) -> np.ndarray:
+        """
+        Converts crystal indices to Cartesian vectors relative
+        to the box's lattice vectors. 
+        
+        Parameters
+        ----------
+        indices : array-like object
+            (..., 3) array of [uvw] Miller crystallographic indices or 
+            (..., 4) array of [uvtw] Miller-Bravais crystallographic indices.
+    
+        Returns
+        -------
+        np.ndarray of float
+            (..., 3) array of Cartesian vectors.
+            
+        Raises
+        ------
+        ValueError
+            If indices dimensions are not (..., 3) or (..., 4), or if
+            hexagonal indices given with non-hexagonal box.
+        """
+        return miller.vector_crystal_to_cartesian(indices, self)
+
+    def plane_crystal_to_cartesian(self, indices: npt.ArrayLike) -> np.ndarray:
+        """
+        Converts crystal planar indices to Cartesian plane normal vectors based
+        on the box's lattice vectors.  Note: the algorithm used requires that the
+        planar indices be integers.
+        
+        Parameters
+        ----------
+        indices : array-like object
+            (..., 3) array of [hkl] Miller crystallographic indices or 
+            (..., 4) array of [hkil] Miller-Bravais crystallographic indices.
+        box : atomman.Box
+            Box that defines the lattice cell vectors to use. 
+    
+        Returns
+        -------
+        np.ndarray of float
+            (..., 3) array of Cartesian vectors corresponding to plane normals.
+            
+        Raises
+        ------
+        ValueError
+            If indices dimensions are not (..., 3) or (..., 4), or if
+            hexagonal indices given with non-hexagonal box.
+        """
+        return miller.plane_crystal_to_cartesian(indices, self)
+
+    def position_relative_to_cartesian(self, relpos: npt.ArrayLike) -> np.ndarray:
+        """
+        Converts position vectors from relative box coordinates to absolute
+        Cartesian coordinates based on the box's vects and origin.
+
+        Parameters
+        ----------
+        relpos : array-like object
+            (..., 3) array of relative position vectors.
+
+        Returns
+        -------
+        numpy.ndarray
+            (..., 3) array of the absolute Cartesian positions corresponding
+            to relpos. 
+
+        Raises
+        ------
+        ValueError
+            If relpos dimensions are not (..., 3).
+        """
+        # Check/convert relpos
+        relpos = np.asarray(relpos, dtype=float)
+        if relpos.shape[-1] != 3:
+            raise ValueError('Invalid position dimensions')
+
+        # Convert and return
+        return relpos.dot(self.vects) + self.origin
+
+    def position_cartesian_to_relative(self, cartpos: npt.ArrayLike) -> np.ndarray:
+        """
+        Converts position vectors from absolute Cartesian coordinates to
+        relative box coordinates based on the box's vects and origin.
+
+        Parameters
+        ----------
+        cartpos : array-like object
+            (..., 3) array of Cartesian position vectors.
+
+        Returns
+        -------
+        numpy.ndarray
+            (..., 3) array of the relative positions corresponding
+            to cartpos. 
+
+        Raises
+        ------
+        ValueError
+            If cartpos dimensions are not (..., 3).
+        """
+        # Check/convert cartpos
+        cartpos = np.asarray(cartpos, dtype=float)
+        if cartpos.shape[-1] != 3:
+            raise ValueError('Invalid position dimensions')
+
+        # Convert and return
+        return np.inner((cartpos - self.origin), self.reciprocal_vects)
+
+    def iscubic(self, 
+                rtol: float = 1e-05,
+                atol: float = 1e-08) -> bool:
+        """
+        Tests if the box is consistent with a standard cubic cell:
+        a = b = c
+        alpha = beta = gamma = 90
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        bool
+            True if the box is a standard cubic cell, False otherwise.
+        """
+        return (np.isclose(self.a, self.b, atol=atol, rtol=rtol)
+                and np.isclose(self.a, self.c, atol=atol, rtol=rtol)
+                and np.isclose(self.alpha, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.beta, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.gamma, 90.0, atol=atol, rtol=rtol))
+
+    def ishexagonal(self,
+                    rtol: float = 1e-05,
+                    atol: float = 1e-08) -> bool:
+        """
+        Tests if the box is consistent with a standard hexagonal cell:
+        a = b != c
+        alpha = beta = 90
+        gamma = 120
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        bool
+            True if the box is a standard hexagonal cell, False otherwise.
+        """
+        return (np.isclose(self.a, self.b, atol=atol, rtol=rtol)
+                and np.isclose(self.alpha, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.beta, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.gamma, 120.0, atol=atol, rtol=rtol))
+
+    def istetragonal(self,
+                     rtol: float = 1e-05,
+                     atol: float = 1e-08) -> bool:
+        """
+        Tests if the box is consistent with a standard tetragonal cell:
+        a = b != c
+        alpha = beta = gamma = 90
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        bool
+            True if the box is a standard tetragonal cell, False otherwise.
+        """
+        return (np.isclose(self.a, self.b, atol=atol, rtol=rtol)
+                and not np.isclose(self.a, self.c, atol=atol, rtol=rtol)
+                and np.isclose(self.alpha, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.beta, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.gamma, 90.0, atol=atol, rtol=rtol))
+
+    def isrhombohedral(self,
+                       rtol: float = 1e-05,
+                       atol: float = 1e-08) -> bool:
+        """
+        Tests if the box is consistent with a standard rhombohedral cell:
+        a = b = c
+        alpha = beta = gamma != 90
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        bool
+            True if the box is a standard rhombohedral cell, False otherwise.
+        """
+        return (np.isclose(self.a, self.b, atol=atol, rtol=rtol)
+                and np.isclose(self.a, self.c, atol=atol, rtol=rtol)
+                and np.isclose(self.alpha, self.beta, atol=atol, rtol=rtol)
+                and np.isclose(self.alpha, self.gamma, atol=atol, rtol=rtol)
+                and not np.isclose(self.alpha, 90.0, atol=atol, rtol=rtol))
+
+    def isorthorhombic(self,
+                       rtol: float = 1e-05,
+                       atol: float = 1e-08) -> bool:
+        """
+        Tests if the box is consistent with a standard orthorhombic cell:
+        a != b != c
+        alpha = beta = gamma = 90
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        bool
+            True if the box is a standard orthorhombic cell, False otherwise.
+        """
+        return (not np.isclose(self.a, self.b, atol=atol, rtol=rtol)
+                and not np.isclose(self.a, self.c, atol=atol, rtol=rtol)
+                and np.isclose(self.alpha, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.beta, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.gamma, 90.0, atol=atol, rtol=rtol))
+
+    def ismonoclinic(self,
+                     rtol: float = 1e-05,
+                     atol: float = 1e-08) -> bool:
+        """
+        Tests if the box is consistent with a standard monoclinic cell:
+        a != b != c
+        alpha = gamma = 90
+        beta != 90
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        bool
+            True if box is a standard monoclinic cell, False otherwise.
+        """
+        return (not np.isclose(self.a, self.b, atol=atol, rtol=rtol)
+                and not np.isclose(self.a, self.c, atol=atol, rtol=rtol)
+                and np.isclose(self.alpha, 90.0, atol=atol, rtol=rtol)
+                and not np.isclose(self.beta, 90.0, atol=atol, rtol=rtol)
+                and np.isclose(self.gamma, 90.0, atol=atol, rtol=rtol))
+
+    def istriclinic(self,
+                    rtol: float = 1e-05,
+                    atol: float = 1e-08) -> bool:
+        """
+        Tests if the box is consistent with a standard triclinic cell:
+        a != b != c
+        alpha != 90
+        beta != 90
+        gamma != 90
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        bool
+            True if box is a standard triclinic cell, False otherwise.
+        """
+        return (not np.isclose(self.a, self.b, atol=atol, rtol=rtol)
+                and not np.isclose(self.a, self.c, atol=atol, rtol=rtol)
+                and not np.isclose(self.alpha, self.beta, atol=atol, rtol=rtol)
+                and not np.isclose(self.alpha, self.gamma, atol=atol, rtol=rtol))
+
+    def identifyfamily(self, 
+                       rtol: float = 1e-05,
+                       atol: float = 1e-08) -> Optional[str]:
+        """
+        Tests if the box is consistent with a standard representation
+        of a crystal system cell.
+        
+        Parameters
+        ----------
+        rtol : float, optional
+            Relative tolerance for testing box parameters. Default value is 1e-5.
+        atol : float, optional
+            Absolute tolerance for testing box parameters. Default value is 1e-8.
+            
+        Returns
+        -------
+        str or None
+            'cubic', 'hexagonal', 'tetragonal', 'rhombohedral', 'orthorhombic',
+            'monoclinic' or 'triclinic' if it matches any. None if no matches.
+            
+        Raises
+        ------
+        ValueError
+            If the box is not consistent with a standard cell.
+        """
+        if self.iscubic(rtol=rtol, atol=atol):
+            return 'cubic'
+        elif self.ishexagonal(rtol=rtol, atol=atol):
+            return 'hexagonal'
+        elif self.istetragonal(rtol=rtol, atol=atol):
+            return 'tetragonal'
+        elif self.isrhombohedral(rtol=rtol, atol=atol):
+            return 'rhombohedral'
+        elif self.isorthorhombic(rtol=rtol, atol=atol):
+            return 'orthorhombic'
+        elif self.ismonoclinic(rtol=rtol, atol=atol):
+            return 'monoclinic'
+        elif self.istriclinic(rtol=rtol, atol=atol):
+            return 'triclinic'
+        else:
+            None
+
+    def d_hkl(self, plane_hkl):
+        """
+        Compute the interplanar spacing for a lattice plane.  Note this feature
+        is expected to be used for only unit cell boxes!
+
+        Parameters
+        ----------
+        plane_hkl : array-like
+            The 3 index Miller or 4 index Miller-Bravais lattice plane.  Values
+            typically are ints, but can be floats if the cell basis is not
+            primitive.
+
+        Returns
+        -------
+        d_hkl : float
+            The spacing between the lattice planes of the given type.
+        """
+        # Check hkl values
+        plane_hkl = np.asarray(plane_hkl)
+        if plane_hkl.shape == (4,):
+            if not self.ishexagonal():
+                raise ValueError('Box is not hexagonal: cannot use 4 index Miller-Bravais plane')
+            plane_hkl = miller.plane4to3(plane_hkl)
+        elif plane_hkl.shape != (3,):
+            raise ValueError('plane_hkl must have 3 or 4 indices')
+        h = plane_hkl[0]
+        k = plane_hkl[1]
+        l = plane_hkl[2]
+
+        a = self.a
+        b = self.b
+        c = self.c
+
+        # Compute sin and cos of the angles
+        sin_alpha = np.sin(self.alpha / 180 * np.pi)
+        sin_beta =  np.sin(self.beta  / 180 * np.pi)
+        sin_gamma = np.sin(self.gamma / 180 * np.pi)
+        cos_alpha = np.cos(self.alpha / 180 * np.pi)
+        cos_beta =  np.cos(self.beta  / 180 * np.pi)
+        cos_gamma = np.cos(self.gamma / 180 * np.pi)
+
+        # Compute the triclinic 1/d_hkl^2 formula
+        numerator = (
+            h**2 / a**2 * sin_alpha**2 +
+            k**2 / b**2 * sin_beta**2 +
+            l**2 / c**2 * sin_gamma**2 +
+            (2 * k * l / b * c) * (cos_beta * cos_gamma - cos_alpha) +
+            (2 * h * l / a * c) * (cos_gamma * cos_alpha - cos_beta) +
+            (2 * h * k / a * b) * (cos_alpha * cos_beta - cos_gamma))
+        denominator = (1 - cos_alpha**2 - cos_beta**2 - cos_gamma**2 +
+                       2 * cos_alpha * cos_beta * cos_gamma)
+        
+        return (numerator / denominator)**-0.5

atomman/source/atomman/core/ElasticConstants.py

@@ -0,0 +1,1037 @@
+# coding: utf-8
+# Standard Python libraries
+from __future__ import annotations
+from copy import deepcopy
+import io
+from typing import Optional, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# atomman imports
+from ..tools import axes_check
+import atomman.unitconvert as uc
+
+class ElasticConstants(object):
+    """Class for storing and converting elastic constant values"""
+    
+    def __init__(self, **kwargs):
+        """
+        Initilizes an ElasticConstants instance from one of the parameter
+        options.
+        
+        Parameters
+        ----------
+        Cij : numpy.ndarray
+            (6, 6) array of Voigt representation of elastic stiffness.
+        Sij : numpy.ndarray
+            (6, 6) array of Voigt representation of elastic compliance.
+        Cij9 : numpy.ndarray
+            (9, 9) array representation of elastic stiffness.
+        Cijkl : numpy.ndarray
+            (3, 3, 3, 3) array representation of elastic stiffness.
+        Sijkl : numpy.ndarray
+            (3, 3, 3, 3) array representation of elastic compliance.
+        model : DataModelDict, string, or file-like object 
+            Data model containing elastic constants.
+        C11, C12, ... C66 : float
+            Individual components of Cij for a standardized representation:
+            isotropic: C11, C12 (see below for more options)
+            cubic: C11, C12, C44
+            hexagonal: C11, C12, C13, C33, C44, C66 (2*C66=C11-C12)
+            tetragonal: C11, C12, C13, C16, C33, C44, C66 (C16 optional)
+            rhombohedral: C11, C12, C13, C14, C15, C33, C44, C66 (2*C66=C11-C12, C15 optional)
+            orthorhombic: C11, C12, C13, C22, C23, C33, C44, C55, C66
+            monoclinic: C11, C12, C13, C15, C22, C23, C25, C33, C35, C44, C46, C55, C66
+            triclinic: all Cij where i <= j
+        M, lambda, mu, E, nu, K, C11, C12, C44 : float
+            Individual isotropic elastic moduli (exactly two must be given).
+        """
+        # Initialize for no arguments
+        if len(kwargs) == 0:
+            self.__c_ij = np.zeros((6,6), dtype='float64')
+        
+        # Initialize for matrix arguments
+        elif 'Cij' in kwargs:
+            assert len(kwargs) == 1, 'Cij cannot be specified with other keyword arguments'
+            self.Cij = kwargs['Cij']
+        elif 'Sij' in kwargs:
+            assert len(kwargs) == 1, 'Sij cannot be specified with other keyword arguments'
+            self.Sij = kwargs['Sij']
+        elif 'Cij9' in kwargs:
+            assert len(kwargs) == 1, 'Cij9 cannot be specified with other keyword arguments'
+            self.Cij9 = kwargs['Cij9']
+        elif 'Cijkl' in kwargs:
+            assert len(kwargs) == 1, 'Cijkl cannot be specified with other keyword arguments'
+            self.Cijkl = kwargs['Cijkl']
+        elif 'Sijkl' in kwargs:
+            assert len(kwargs) == 1, 'Sijkl cannot be specified with other keyword arguments'
+            self.Sijkl = kwargs['Sijkl']
+        
+        # Initialize using data model
+        elif 'model' in kwargs:
+            self.model(**kwargs)
+        
+        # Initialize for individually specified parameters
+        elif len(kwargs) == 2:
+            self.isotropic(**kwargs)
+        elif len(kwargs) == 3:
+            self.cubic(**kwargs)
+        elif len(kwargs) == 5:
+            self.hexagonal(**kwargs)
+        elif len(kwargs) == 6 or len(kwargs) == 7:
+            if 'C14' in kwargs:
+                self.rhombohedral(**kwargs)
+            else:
+                self.tetragonal(**kwargs)
+        elif len(kwargs) == 8:
+            self.rhombohedral(**kwargs)
+        elif len(kwargs) == 9:
+            self.orthorhombic(**kwargs)
+        elif len(kwargs) == 13:
+            self.monoclinic(**kwargs)
+        elif len(kwargs) == 21:
+            self.triclinic(**kwargs)
+        else:
+            raise TypeError('Invalid argument keywords')
+    
+    def __str__(self)  -> str:
+        """Calling string returns str(self.Cij)."""
+        return str(self.Cij)
+    
+    @property
+    def Cij(self) -> np.ndarray:
+        """The stiffness constants in Voigt 6x6 format"""
+        return deepcopy(self.__c_ij)
+    
+    @Cij.setter
+    def Cij(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype='float64')
+        assert value.shape == (6,6),  'Cij must be 6x6'
+        
+        # Zero out near-zero terms
+        assert value.max() > 0.0, 'Cij values not valid'
+        value[np.isclose(value/value.max(), 0.0, atol=1e-9)] = 0.0
+        
+        # Check symmetry
+        for i in range(6):
+            for j in range(i):
+                assert np.isclose(value[i,j], value[j,i], atol=1e-9), '6x6 matrix not symmetric!' 
+        self.__c_ij = value
+    
+    @property
+    def Sij(self) -> np.ndarray:
+        """The compliance constants in Voigt 6x6 format"""
+        return np.linalg.inv(self.Cij)
+    
+    @Sij.setter
+    def Sij(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype='float64')
+        assert value.shape == (6,6),  'Sij must be 6x6'
+        self.Cij = np.linalg.inv(value)
+    
+    @property
+    def Cij9(self) -> np.ndarray:
+        """The stiffness constants in 9x9 format"""
+        c = self.Cij
+        return np.array([[c[0,0],c[0,1],c[0,2],c[0,3],c[0,4],c[0,5],c[0,3],c[0,4],c[0,5]],
+                         [c[1,0],c[1,1],c[1,2],c[1,3],c[1,4],c[1,5],c[1,3],c[1,4],c[1,5]],
+                         [c[2,0],c[2,1],c[2,2],c[2,3],c[2,4],c[2,5],c[2,3],c[2,4],c[2,5]],
+                         [c[3,0],c[3,1],c[3,2],c[3,3],c[3,4],c[3,5],c[3,3],c[3,4],c[3,5]],
+                         [c[4,0],c[4,1],c[4,2],c[4,3],c[4,4],c[4,5],c[4,3],c[4,4],c[4,5]],
+                         [c[5,0],c[5,1],c[5,2],c[5,3],c[5,4],c[5,5],c[5,3],c[5,4],c[5,5]],
+                         [c[3,0],c[3,1],c[3,2],c[3,3],c[3,4],c[3,5],c[3,3],c[3,4],c[3,5]],
+                         [c[4,0],c[4,1],c[4,2],c[4,3],c[4,4],c[4,5],c[4,3],c[4,4],c[4,5]],
+                         [c[5,0],c[5,1],c[5,2],c[5,3],c[5,4],c[5,5],c[5,3],c[5,4],c[5,5]]])
+    
+    @Cij9.setter
+    def Cij9(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype='float64')
+        assert value.shape == (9,9), 'Cij9 must be 9x9'
+        
+        # Check symmetry
+        for i in range(6, 9):
+            for j in range(9):
+                assert value[i,j] == value[i-3, j]
+                assert value[j,i] == value[j, i-3]
+        self.Cij = value[:6, :6]
+    
+    @property
+    def Cijkl(self) -> np.ndarray:
+        """The stiffness constants in 3x3x3x3 format"""
+        c = self.Cij
+        return np.array([[[[c[0,0],c[0,5],c[0,4]], [c[0,5],c[0,1],c[0,3]], [c[0,4],c[0,3],c[0,2]]],
+                          [[c[5,0],c[5,5],c[5,4]], [c[5,5],c[5,1],c[5,3]], [c[5,4],c[5,3],c[5,2]]],
+                          [[c[4,0],c[4,5],c[4,4]], [c[4,5],c[4,1],c[4,3]], [c[4,4],c[4,3],c[4,2]]]], 
+                        
+                         [[[c[5,0],c[5,5],c[5,4]], [c[5,5],c[5,1],c[5,3]], [c[5,4],c[5,3],c[5,2]]],
+                          [[c[1,0],c[1,5],c[1,4]], [c[1,5],c[1,1],c[1,3]], [c[1,4],c[1,3],c[1,2]]],
+                          [[c[3,0],c[3,5],c[3,4]], [c[3,5],c[3,1],c[3,3]], [c[3,4],c[3,3],c[3,2]]]],
+                         
+                         [[[c[4,0],c[4,5],c[4,4]], [c[4,5],c[4,1],c[4,3]], [c[4,4],c[4,3],c[4,2]]],
+                          [[c[3,0],c[3,5],c[3,4]], [c[3,5],c[3,1],c[3,3]], [c[3,4],c[3,3],c[3,2]]],
+                          [[c[2,0],c[2,5],c[2,4]], [c[2,5],c[2,1],c[2,3]], [c[2,4],c[2,3],c[2,2]]]]])
+    
+    @Cijkl.setter
+    def Cijkl(self, value: npt.ArrayLike):
+        c = np.asarray(value, dtype='float64')
+        assert c.shape == (3,3,3,3),  'Cijkl must be 3x3x3x3'
+        assert c.max() > 0.0, 'Cij values not valid'
+        # Check symmetry
+        indexes = np.array([[0,0], [1,1], [2,2], [1,2], [0,2], [0,1]], dtype=int)
+        for ij in range(6):
+            for kl in range(ij, 6):
+                i, j, k, l = indexes[ij,0], indexes[ij,1], indexes[kl,0], indexes[kl,1]
+                assert np.isclose(c[i,j,k,l], c[j,i,k,l])
+                assert np.isclose(c[i,j,k,l], c[j,i,l,k])
+                assert np.isclose(c[i,j,k,l], c[k,l,j,i])
+                assert np.isclose(c[i,j,k,l], c[l,k,j,i])
+                assert np.isclose(c[i,j,k,l], c[i,j,l,k])
+                assert np.isclose(c[i,j,k,l], c[k,l,i,j])
+                assert np.isclose(c[i,j,k,l], c[l,k,i,j])
+        
+        self.Cij = np.array([[c[0,0,0,0], c[0,0,1,1], c[0,0,2,2], c[0,0,1,2], c[0,0,0,2], c[0,0,0,1]],
+                             [c[1,1,0,0], c[1,1,1,1], c[1,1,2,2], c[1,1,1,2], c[1,1,0,2], c[1,1,0,1]],
+                             [c[2,2,0,0], c[2,2,1,1], c[2,2,2,2], c[2,2,1,2], c[2,2,0,2], c[2,2,0,1]],
+                             [c[1,2,0,0], c[1,2,1,1], c[1,2,2,2], c[1,2,1,2], c[1,2,0,2], c[1,2,0,1]],
+                             [c[0,2,0,0], c[0,2,1,1], c[0,2,2,2], c[0,2,1,2], c[0,2,0,2], c[0,2,0,1]],
+                             [c[0,1,0,0], c[0,1,1,1], c[0,1,2,2], c[0,1,1,2], c[0,1,0,2], c[0,1,0,1]]])
+    
+    @property
+    def Sijkl(self) -> np.ndarray:
+        """The compliance constants in 3x3x3x3 format"""
+        s = self.Sij
+        s[3:,:] = s[3:,:]/2.
+        s[:,3:] = s[:,3:]/2.
+        return np.array([[[[s[0,0],s[0,5],s[0,4]], [s[0,5],s[0,1],s[0,3]], [s[0,4],s[0,3],s[0,2]]],
+                          [[s[5,0],s[5,5],s[5,4]], [s[5,5],s[5,1],s[5,3]], [s[5,4],s[5,3],s[5,2]]],
+                          [[s[4,0],s[4,5],s[4,4]], [s[4,5],s[4,1],s[4,3]], [s[4,4],s[4,3],s[4,2]]]],
+                         
+                         [[[s[5,0],s[5,5],s[5,4]], [s[5,5],s[5,1],s[5,3]], [s[5,4],s[5,3],s[5,2]]],
+                          [[s[1,0],s[1,5],s[1,4]], [s[1,5],s[1,1],s[1,3]], [s[1,4],s[1,3],s[1,2]]],
+                          [[s[3,0],s[3,5],s[3,4]], [s[3,5],s[3,1],s[3,3]], [s[3,4],s[3,3],s[3,2]]]],
+                         
+                         [[[s[4,0],s[4,5],s[4,4]], [s[4,5],s[4,1],s[4,3]], [s[4,4],s[4,3],s[4,2]]],
+                          [[s[3,0],s[3,5],s[3,4]], [s[3,5],s[3,1],s[3,3]], [s[3,4],s[3,3],s[3,2]]],
+                          [[s[2,0],s[2,5],s[2,4]], [s[2,5],s[2,1],s[2,3]], [s[2,4],s[2,3],s[2,2]]]]])
+    
+    @Sijkl.setter
+    def Sijkl(self, value: npt.ArrayLike):
+        s = np.asarray(value, dtype='float64')
+        assert s.shape == (3,3,3,3),  'Sijkl must be 3x3x3x3'
+        
+        # Check symmetry
+        indexes = np.array([[0,0], [1,1], [2,2], [1,2], [0,2], [0,1]], dtype=int)
+        for ij in range(6):
+            for kl in range(ij, 6):
+                i, j, k, l = indexes[ij,0], indexes[ij,1], indexes[kl,0], indexes[kl,1]
+                assert np.isclose(s[i,j,k,l], s[j,i,k,l])
+                assert np.isclose(s[i,j,k,l], s[j,i,l,k])
+                assert np.isclose(s[i,j,k,l], s[k,l,j,i])
+                assert np.isclose(s[i,j,k,l], s[l,k,j,i])
+                assert np.isclose(s[i,j,k,l], s[i,j,l,k])
+                assert np.isclose(s[i,j,k,l], s[k,l,i,j])
+                assert np.isclose(s[i,j,k,l], s[l,k,i,j]) 
+        
+        self.Sij = np.array([[   s[0,0,0,0],    s[0,0,1,1],    s[0,0,2,2], 2.*s[0,0,1,2], 2.*s[0,0,0,2], 2.*s[0,0,0,1]],
+                             [   s[1,1,0,0],    s[1,1,1,1],    s[1,1,2,2], 2.*s[1,1,1,2], 2.*s[1,1,0,2], 2.*s[1,1,0,1]],
+                             [   s[2,2,0,0],    s[2,2,1,1],    s[2,2,2,2], 2.*s[2,2,1,2], 2.*s[2,2,0,2], 2.*s[2,2,0,1]],
+                             [2.*s[1,2,0,0], 2.*s[1,2,1,1], 2.*s[1,2,2,2], 4.*s[1,2,1,2], 4.*s[1,2,0,2], 4.*s[1,2,0,1]],
+                             [2.*s[0,2,0,0], 2.*s[0,2,1,1], 2.*s[0,2,2,2], 4.*s[0,2,1,2], 4.*s[0,2,0,2], 4.*s[0,2,0,1]],
+                             [2.*s[0,1,0,0], 2.*s[0,1,1,1], 2.*s[0,1,2,2], 4.*s[0,1,1,2], 4.*s[0,1,0,2], 4.*s[0,1,0,1]]])
+    
+    def transform(self,
+                  axes: npt.ArrayLike,
+                  tol: float = 1e-8) -> ElasticConstants:
+        """
+        Transforms the elastic constant matrix based on the supplied axes.
+        
+        Parameters
+        ----------
+        axes : numpy.ndarray
+            (3, 3) array giving three right-handed orthogonal vectors to use
+            for transforming.
+        tol : float, optional
+            Relative tolerance to use in identifying near-zero terms.
+            
+        Returns
+        -------
+        ElasticConstants
+            A new ElasticConstants object that has been transformed.
+        """
+        axes = np.asarray(axes, dtype='float64')
+        T = axes_check(axes)
+        
+        Q = np.einsum('km,ln->mnkl', T, T)
+        C = np.einsum('ghij,ghmn,mnkl->ijkl', Q, self.Cijkl, Q)
+        C[abs(C / C.max()) < tol] = 0.0
+        
+        return ElasticConstants(Cijkl=C)
+    
+    def isotropic(self, **kwargs):
+        """
+        Set values with two independent isotropic moduli.
+        
+        Parameters
+        ----------
+        C11 : float, optional
+            C11 component of Cij.
+        C12 : float, optional
+            C12 component of Cij.
+        C44 : float, optional
+            C44 component of Cij.
+        M : float, optional
+            P-wave modulus(Equivalent to C11).
+        lambda : float, optional
+            Lame's first parameter (Equivalent to C12).
+        mu : float, optional
+            Shear modulus (Equivalent to C44).
+        E : float, optional
+            Young's modulus
+        nu : float, optional
+            Poisson's ratio
+        K : float, optional
+            Bulk modulus
+        """
+        
+        try:
+            # Handle equivalent terms
+            if 'M' in kwargs:
+                kwargs['C11'] = kwargs.pop('M')
+            if 'lambda' in kwargs:
+                kwargs['C12'] = kwargs.pop('lambda')
+            if 'mu' in kwargs:
+                kwargs['C44'] = kwargs.pop('mu')
+            
+            # Check len of kwargs
+            assert len(kwargs) == 2
+            
+            # Pop and convert terms
+            if 'C11' in kwargs:
+                c11 = kwargs.pop('C11')
+                
+                if 'C12' in kwargs:
+                    c12 = kwargs.pop('C12')
+                    c44 = (c11 - c12) / 2
+                
+                else:
+                    if 'C44' in kwargs:
+                        c44 = kwargs.pop('C44')
+                    
+                    elif 'E' in kwargs: 
+                        E = kwargs.pop('E')
+                        S = (E**2 + 9 * c11**2 - 10 * E * c11)**0.5
+                        c44 = (3 * c11 + E - S) / 8
+                    
+                    elif 'nu' in kwargs: 
+                        nu = kwargs.pop('nu')
+                        c44 = c11 * (1 - 2 * nu) / (2 * (1 - nu))
+                    
+                    elif 'K' in kwargs: 
+                        K = kwargs.pop('K')
+                        c44 = 3 * (c11 - K) / 4
+                    
+                    c12 = c11 - 2 * c44
+            
+            else:
+                if 'C12' in kwargs:
+                    c12 = kwargs.pop('C12')
+                    
+                    if 'C44' in kwargs:
+                        c44 = kwargs.pop('C44')
+                    
+                    elif 'E' in kwargs:
+                        E = kwargs.pop('E')
+                        R = (E**2 + 9 * c12**2 + 2 * E * c12)**0.5
+                        c44 = (E - 3 * c12 + R) / 4
+                    
+                    elif 'nu' in kwargs:
+                        nu = kwargs.pop('nu')
+                        c44 = c12 * (1 - 2 * nu) / (2 * nu)
+                    
+                    elif 'K' in kwargs:
+                        K = kwargs.pop('K')
+                        c44 = 3 * (K - c12) / 2
+                
+                elif 'C44' in kwargs:
+                    c44 = kwargs.pop('C44')
+                    
+                    if 'E' in kwargs:
+                        E = kwargs.pop('E')
+                        c12 = c44 * (E - 2 * c44) / (3 * c44 - E)
+                    
+                    elif 'nu' in kwargs:
+                        nu = kwargs.pop('nu')
+                        c12 = 2 * c44 * nu / (1 - 2 * nu)
+                    
+                    elif 'K' in kwargs:
+                        K = kwargs.pop('K')
+                        c12 = K - 2 * c44 / 3
+                
+                elif 'E' in kwargs: 
+                    E = kwargs.pop('E')
+                    
+                    if 'nu' in kwargs: 
+                        nu = kwargs.pop('nu')
+                        c12 = E * nu / ((1 + nu) * (1 - 2 * nu))
+                        c44 = E / (2 * (1 + nu))
+                    
+                    elif 'K' in kwargs: 
+                        K = kwargs.pop('K')
+                        c12 = 3 * K * (3 * K - E) / (9 * K - E)
+                        c44 = 3 * K * E / (9 * K - E)
+                
+                elif 'nu' in kwargs:
+                    nu = kwargs.pop('nu')
+                    
+                    if 'K' in kwargs: 
+                        K = kwargs.pop('K')
+                        c12 = 3 * K * nu / (1 + nu)
+                        c44 = 3 * K * (1 - 2 * nu) / (2 * (1 + nu))
+                
+                c11 = c12 + 2 * c44
+        
+        except:
+            raise TypeError('isotropic style takes two unique keyword arguments of (C11=M, C12=lambda, C44=mu, E, nu, K)')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c12, 0.0, 0.0, 0.0],
+                             [c12, c11, c12, 0.0, 0.0, 0.0],
+                             [c12, c12, c11, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, c44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, c44, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, c44]]) 
+    
+    def cubic(self, **kwargs):
+        """
+        Set values with three independent cubic moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        """
+        
+        try:
+            # Check len of kwargs
+            assert len(kwargs) == 3
+            
+            # Pop required independent terms
+            c11 = kwargs.pop('C11')
+            c12 = kwargs.pop('C12')
+            c44 = kwargs.pop('C44')
+        except:
+            raise TypeError('cubic style takes keyword arguments C11, C12, and C66')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c12, 0.0, 0.0, 0.0],
+                             [c12, c11, c12, 0.0, 0.0, 0.0],
+                             [c12, c12, c11, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, c44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, c44, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, c44]])
+    
+    def hexagonal(self, **kwargs):
+        """
+        Set values with five independent hexagonal moduli.
+        (2 * C66 = C11 - C12)
+        
+        Parameters
+        ----------
+        C11 : float, optional
+            C11 component of Cij.
+        C12 : float, optional
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C66 : float, optional
+            C66 component of Cij.
+        """
+        
+        try:
+            # Check len of kwargs
+            assert len(kwargs) >= 5 and len(kwargs) <=6
+            
+            # Pop required independent terms
+            c33 = kwargs.pop('C33')
+            c13 = kwargs.pop('C13')
+            c44 = kwargs.pop('C44')
+            
+            # Pop required dependent terms
+            if 'C11' in kwargs and 'C12' in kwargs:
+                c11 = kwargs.pop('C11')
+                c12 = kwargs.pop('C12')
+                c66 = (c11 - c12) / 2
+                
+                # Check if redundant C66 is given
+                if 'C66' in kwargs:
+                    assert np.isclose(c66, kwargs['C66'])
+                    c66 = kwargs.pop('C66')
+            
+            elif 'C11' in kwargs and 'C66' in kwargs:
+                c11 = kwargs.pop('C11')
+                c66 = kwargs.pop('C66')
+                c12 = c11 - 2 * c66
+            
+            elif 'C12' in kwargs and 'C66' in kwargs:
+                c12 = kwargs.pop('C12')
+                c66 = kwargs.pop('C66')
+                c11 = 2 * c66 + c12
+            else:
+                assert False
+        except:
+            raise TypeError('hexagonal style takes keyword arguments C33, C13, C44, and two of (2*C66=C11-C12)')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c13, 0.0, 0.0, 0.0],
+                             [c12, c11, c13, 0.0, 0.0, 0.0],
+                             [c13, c13, c33, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, c44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, c44, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, c66]])
+    
+    def rhombohedral(self, **kwargs):
+        """
+        Set values with six or seven independent rhombohedral moduli. 
+        (2 * C66 = C11 - C12)
+        
+        Parameters
+        ----------
+        C11 : float, optional
+            C11 component of Cij.
+        C12 : float, optional
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C14 : float
+            C14 component of Cij.
+        C15 : float, optional
+            C15 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C66 : float, optional
+            C66 component of Cij.
+        """
+        
+        try:
+            # Check len of kwargs
+            assert len(kwargs) >= 6 and len(kwargs) <= 8
+            
+            # Pop required independent terms
+            c33 = kwargs.pop('C33')
+            c13 = kwargs.pop('C13')
+            c14 = kwargs.pop('C14')
+            c44 = kwargs.pop('C44')
+            
+            # Pop required dependent terms
+            if 'C11' in kwargs and 'C12' in kwargs:
+                c11 = kwargs.pop('C11')
+                c12 = kwargs.pop('C12')
+                c66 = (c11 - c12) / 2
+                
+                # Check if redundant C66 is given
+                if 'C66' in kwargs:
+                    assert np.isclose(c66, kwargs['C66'])
+                    c66 = kwargs.pop('C66')
+            
+            elif 'C11' in kwargs and 'C66' in kwargs:
+                c11 = kwargs.pop('C11')
+                c66 = kwargs.pop('C66')
+                c12 = c11 - 2 * c66
+            
+            elif 'C12' in kwargs and 'C66' in kwargs:
+                c12 = kwargs.pop('C12')
+                c66 = kwargs.pop('C66')
+                c11 = 2 * c66 + c12
+            else:
+                assert False
+            
+            # Check for optional term
+            if len(kwargs) == 0:
+                c15 = 0.0
+            else:
+                c15 = kwargs.pop('C15')
+                assert len(kwargs) == 0
+        except:
+            raise TypeError('rhombohedral style takes keyword arguments C33, C13, C14, C44, at least two of (2*C66=C11-C12) and optional C15')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c13, c14, c15, 0.0],
+                             [c12, c11, c13,-c14,-c15, 0.0],
+                             [c13, c13, c33, 0.0, 0.0, 0.0],
+                             [c14,-c14, 0.0, c44, 0.0,-c15],
+                             [c15,-c15, 0.0, 0.0, c44, c14],
+                             [0.0, 0.0, 0.0,-c15, c14, c66]])
+    
+    def tetragonal(self, **kwargs):
+        """
+        Set values with six or seven independent tetragonal moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C16 : float, optional
+            C16 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        
+        try:
+            # Check len of kwargs
+            assert len(kwargs) == 6 or len(kwargs) == 7
+            
+            # Pop required independent terms
+            c11 = kwargs.pop('C11')
+            c33 = kwargs.pop('C33')
+            c12 = kwargs.pop('C12')
+            c13 = kwargs.pop('C13')
+            c44 = kwargs.pop('C44')
+            c66 = kwargs.pop('C66')
+            
+            # Check for optional term
+            if len(kwargs) == 0:
+                c16 = 0.0
+            else:
+                c16 = kwargs.pop('C16')
+                assert len(kwargs) == 0
+        except:
+            raise TypeError('tetragonal style takes keyword arguments C11, C33, C12, C13, C44, C66, and optional C16')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c13, 0.0, 0.0, c16],
+                             [c12, c11, c13, 0.0, 0.0,-c16],
+                             [c13, c13, c33, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, c44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, c44, 0.0],
+                             [c16,-c16, 0.0, 0.0, 0.0, c66]])
+    
+    def orthorhombic(self, **kwargs):
+        """
+        Set values with nine independent orthorhombic moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C22 : float
+            C22 component of Cij.
+        C23 : float
+            C23 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C55 : float
+            C55 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        
+        try:
+            # Check len of kwargs
+            assert len(kwargs) == 9
+            
+            # Set required independent terms
+            c11 = kwargs['C11']
+            c22 = kwargs['C22']
+            c33 = kwargs['C33']
+            c12 = kwargs['C12']
+            c13 = kwargs['C13']
+            c23 = kwargs['C23']
+            c44 = kwargs['C44']
+            c55 = kwargs['C55']
+            c66 = kwargs['C66']
+        except:
+            raise TypeError('orthorhombic style takes keyword arguments C11, C22, C33, C12, C13, C23, C44, C55, C66')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c13, 0.0, 0.0, 0.0],
+                             [c12, c22, c23, 0.0, 0.0, 0.0],
+                             [c13, c23, c33, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, c44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, c55, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, c66]])
+    
+    def monoclinic(self, **kwargs):
+        """
+        Set values with thirteen independent monoclinic moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C15 : float
+            C15 component of Cij.
+        C22 : float
+            C22 component of Cij.
+        C23 : float
+            C23 component of Cij.
+        C25 : float
+            C25 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C35 : float
+            C35 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C46 : float
+            C46 component of Cij.
+        C55 : float
+            C55 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        
+        try:
+            # Check len of kwargs
+            assert len(kwargs) == 13
+            
+            # Set required independent terms
+            c11 = kwargs['C11']
+            c12 = kwargs['C12']
+            c13 = kwargs['C13']
+            c15 = kwargs['C15']
+            c22 = kwargs['C22']
+            c23 = kwargs['C23']
+            c25 = kwargs['C25']
+            c33 = kwargs['C33']
+            c35 = kwargs['C35']
+            c44 = kwargs['C44']
+            c46 = kwargs['C46']
+            c55 = kwargs['C55']
+            c66 = kwargs['C66']
+        except:
+            raise TypeError('monoclinic style takes keyword arguments C11, C12, C13, C15, C22, C23, C25, C33, C35, C44, C46, C55, C66')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c13, 0.0, c15, 0.0],
+                             [c12, c22, c23, 0.0, c25, 0.0],
+                             [c13, c23, c33, 0.0, c35, 0.0],
+                             [0.0, 0.0, 0.0, c44, 0.0, c46],
+                             [c15, c25, c35, 0.0, c55, 0.0],
+                             [0.0, 0.0, 0.0, c46, 0.0, c66]])
+    
+    def triclinic(self, **kwargs):
+        """
+        Set values with twenty one independent triclinic moduli
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C14 : float
+            C14 component of Cij.
+        C15 : float
+            C15 component of Cij.
+        C16 : float
+            C16 component of Cij.
+        C22 : float
+            C22 component of Cij.
+        C23 : float
+            C23 component of Cij.
+        C24 : float
+            C24 component of Cij.
+        C25 : float
+            C25 component of Cij.
+        C26 : float
+            C26 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C34 : float
+            C34 component of Cij.
+        C35 : float
+            C35 component of Cij.
+        C36 : float
+            C36 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C45 : float
+            C45 component of Cij.
+        C46 : float
+            C46 component of Cij.
+        C55 : float
+            C55 component of Cij.
+        C56 : float
+            C56 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        
+        try:
+            # Check len of kwargs
+            assert len(kwargs) == 21
+            
+            # Set required independent terms
+            c11 = kwargs['C11']
+            c12 = kwargs['C12']
+            c13 = kwargs['C13']
+            c14 = kwargs['C14']
+            c15 = kwargs['C15']
+            c16 = kwargs['C16']
+            c22 = kwargs['C22']
+            c23 = kwargs['C23']
+            c24 = kwargs['C24']
+            c25 = kwargs['C25']
+            c26 = kwargs['C26']
+            c33 = kwargs['C33']
+            c34 = kwargs['C34']
+            c35 = kwargs['C35']
+            c36 = kwargs['C36']
+            c44 = kwargs['C44']
+            c45 = kwargs['C45']
+            c46 = kwargs['C46']
+            c55 = kwargs['C55']
+            c56 = kwargs['C56']
+            c66 = kwargs['C66']
+        except:
+            raise TypeError('triclinic style takes keyword arguments of all Cij where i <= j')
+        
+        # Build Cij array
+        self.Cij = np.array([[c11, c12, c13, c14, c15, c16],
+                             [c12, c22, c23, c24, c25, c26],
+                             [c13, c23, c33, c34, c35, c36],
+                             [c14, c24, c34, c44, c45, c46],
+                             [c15, c25, c35, c45, c55, c56],
+                             [c16, c26, c36, c46, c56, c66]])
+    
+    def normalized_as(self, crystal_system: str) -> ElasticConstants:
+        """
+        Returns a new ElasticConstants object where values of the current are
+        averaged or zeroed out according to a standard crystal system setting.
+        NOTE: no validation checks are made to evaluate whether such
+        normalizations should be done! That is left up to you (compare values
+        before and after normalization).
+        
+        Parameters
+        ----------
+        crystal_system : str
+            Indicates the crystal system representation to use when building a
+            data model.
+            
+        Returns
+        -------
+        atomman.ElasticConstants
+            The elastic constants normalized according to the crystal system
+            symmetries.
+        """
+        
+        if crystal_system == 'triclinic':
+            return ElasticConstants(Cij = self.Cij)
+        
+        else:
+            c = self.Cij
+            c_dict = {}
+            
+            if crystal_system == 'isotropic':
+                c_dict['mu'] = self.shear()
+                c_dict['K'] = self.bulk()
+            
+            elif crystal_system == 'cubic':
+                c_dict['C11'] = (c[0,0] + c[1,1] + c[2,2]) / 3
+                c_dict['C12'] = (c[0,1] + c[0,2] + c[1,2]) / 3
+                c_dict['C44'] = (c[3,3] + c[4,4] + c[5,5]) / 3
+            
+            elif crystal_system == 'hexagonal':
+                c_dict['C11'] = (c[0,0] + c[1,1]) / 2
+                c_dict['C33'] = c[2,2]
+                c_dict['C12'] = (c[0,1] + (c[0,0] - 2*c[5,5])) / 2
+                c_dict['C13'] = (c[0,2] + c[1,2]) / 2
+                c_dict['C44'] = (c[3,3] + c[4,4]) / 2
+            
+            elif crystal_system == 'tetragonal':
+                c_dict['C11'] = (c[0,0] + c[1,1]) / 2
+                c_dict['C33'] = c[2,2]
+                c_dict['C12'] = c[0,1]
+                c_dict['C13'] = (c[0,2] + c[1,2]) / 2
+                c_dict['C16'] = (c[0,5] - c[1,5]) / 2
+                c_dict['C44'] = (c[3,3] + c[4,4]) / 2
+                c_dict['C66'] = c[5,5]
+            
+            elif crystal_system == 'rhombohedral':
+                c_dict['C11'] = (c[0,0] + c[1,1]) / 2
+                c_dict['C33'] = c[2,2]
+                c_dict['C12'] = (c[0,1] + (c[0,0] - 2*c[5,5])) / 2
+                c_dict['C13'] = (c[0,2] + c[1,2]) / 2
+                c_dict['C14'] = (c[0,3] - c[1,3]) / 2
+                c_dict['C15'] = (c[0,4] - c[1,4] - c[3,5]) / 3
+                c_dict['C44'] = (c[3,3] + c[4,4]) / 2
+            
+            elif crystal_system == 'orthorhombic':
+                c_dict['C11'] = c[0,0]
+                c_dict['C22'] = c[1,1]
+                c_dict['C33'] = c[2,2]
+                c_dict['C12'] = c[0,1]
+                c_dict['C13'] = c[0,2]
+                c_dict['C23'] = c[1,2]
+                c_dict['C44'] = c[3,3]
+                c_dict['C55'] = c[4,4]
+                c_dict['C66'] = c[5,5]
+            else:
+                raise ValueError('Invalid crystal_system: ' + crystal_system)
+            
+            return ElasticConstants(**c_dict)
+    
+    def is_normal(self,
+                  crystal_system: str,
+                  atol: float = 1e-4,
+                  rtol: float = 1e-4) -> bool:
+        """
+        Checks if current elastic constants agree with values normalized to
+        a specified crystal family (within tolerances).
+        
+        Parameters
+        ----------
+        crystal_system : str
+            Indicates the crystal system representation to use when building a
+            data model.
+        atol : float, optional
+            Absolute tolerance to use.  Default value is 1e-4.
+        rtol : float, optional
+            Relative tolerance to use.  Default value is 1e-4.
+        
+        Returns
+        -------
+        bool
+            True if all Cij match within the tolerances, false otherwise.
+        """
+        return np.allclose(self.Cij, self.normalized_as(crystal_system).Cij,
+                           atol=atol, rtol=rtol)
+    
+    def model(self,
+              model: Union[str, io.IOBase, DM, None] = None,
+              unit: Optional[str] = None,
+              crystal_system: str = 'triclinic') -> Optional[DM]:
+        """
+        Return or set DataModelDict representation of the elastic constants.
+        
+        Parameters
+        ----------
+        model : DataModelDict, string, or file-like object, optional
+            Data model containing exactly one 'elastic-constants' branch to
+            read.
+        unit : str, optional
+            Units or pressure to save values in when building a data model.
+            Default value is None (no conversion).
+        crystal_system : str, optional
+            Indicates the crystal system representation to normalize by.
+            Default value is 'triclinic', i.e. no normalization.
+        
+        Returns
+        -------
+        DataModelDict
+            If model is not given as a parameter.
+        """
+        
+        # Set values if model given
+        if model is not None:
+            
+            # Find elastic-constants element
+            model = DM(model).find('elastic-constants')
+            
+            # Read in values
+            try:
+                # New format
+                self.Cij = uc.value_unit(model['Cij'])
+            except:
+                # Old format
+                c_dict = {}
+                for C in model['C']:
+                    key = 'C' + C['ij'][0] + C['ij'][2]
+                    c_dict[key] = uc.value_unit(C['stiffness'])
+                self.Cij = ElasticConstants(**c_dict).Cij 
+        
+        # Return DataModelDict if model not given
+        else:
+            normCij = self.normalized_as(crystal_system).Cij
+            model = DM()
+            model['elastic-constants'] = DM()
+            model['elastic-constants']['Cij'] = uc.model(normCij, unit)
+            
+            return model
+    
+    def bulk(self, style: str = 'Hill') -> float:
+        """
+        Returns a bulk modulus estimate.
+        
+        Parameters
+        ----------
+        style : str
+            Indicates which style of estimate to use.  Default value is 'Hill'.
+            - 'Hill' -- Hill estimate (average of Voigt and Reuss).
+            - 'Voigt' -- Voigt estimate. Uses Cij.
+            - 'Reuss' -- Reuss estimate. Uses Sij.
+        """
+        if style == 'Hill':
+            return (self.bulk('Voigt') + self.bulk('Reuss')) / 2
+        
+        elif style == 'Voigt':
+            c = self.Cij
+            return ( (c[0,0] + c[1,1] + c[2,2]) + 2*(c[0,1] + c[1,2] + c[0,2]) ) / 9
+        
+        elif style == 'Reuss':
+            s = self.Sij
+            return 1 / ( (s[0,0] + s[1,1] + s[2,2]) + 2*(s[0,1] + s[1,2] + s[0,2]) )
+        
+        else:
+            raise ValueError('Unknown estimate style')
+    
+    def shear(self, style: str = 'Hill') -> float:
+        """
+        Returns a shear modulus estimate.
+        
+        Parameters
+        ----------
+        style : str
+            Indicates which style of estimate to use.  Default value is 'Hill'.
+            - 'Hill' -- Hill estimate (average of Voigt and Reuss).
+            - 'Voigt' -- Voigt estimate. Uses Cij.
+            - 'Reuss' -- Reuss estimate. Uses Sij.
+        """
+        if style == 'Hill':
+            return (self.shear('Voigt') + self.shear('Reuss')) / 2
+        
+        elif style == 'Voigt':
+            c = self.Cij
+            return ( (c[0,0] + c[1,1] + c[2,2]) - (c[0,1] + c[1,2] + c[0,2]) + 3*(c[3,3] + c[4,4] + c[5,5]) ) / 15
+        
+        elif style == 'Reuss':
+            s = self.Sij
+            return 15 / ( 4*(s[0,0] + s[1,1] + s[2,2]) - 4*(s[0,1] + s[1,2] + s[0,2]) + 3*(s[3,3] + s[4,4] + s[5,5]) )
+        
+        else:
+            raise ValueError('Unknown estimate style')

atomman/source/atomman/core/ElasticConstants2.py

@@ -0,0 +1,1017 @@
+# coding: utf-8
+# Standard Python libraries
+from __future__ import annotations
+from copy import deepcopy
+import io
+from typing import Optional, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# atomman imports
+from ..tools import axes_check
+import atomman.unitconvert as uc
+
+class ElasticConstants2(object):
+    """Class for storing and converting elastic constant values"""
+
+    def __init__(self, **kwargs):
+        """
+        Initializes an ElasticConstants instance from one of the parameter
+        options.
+        
+        Parameters
+        ----------
+        Cij : numpy.ndarray
+            (6, 6) array of Voigt representation of elastic stiffness.
+        Sij : numpy.ndarray
+            (6, 6) array of Voigt representation of elastic compliance.
+        Cij9 : numpy.ndarray
+            (9, 9) array representation of elastic stiffness.
+        Cijkl : numpy.ndarray
+            (3, 3, 3, 3) array representation of elastic stiffness.
+        Sijkl : numpy.ndarray
+            (3, 3, 3, 3) array representation of elastic compliance.
+        model : DataModelDict, string, or file-like object 
+            Data model containing elastic constants.
+        C11, C12, ... C66 : float
+            Individual components of Cij for a standardized representation:
+            isotropic: C11, C12, C44 (2*C44=C11-C12)
+            cubic: C11, C12, C44
+            hexagonal: C11, C12, C13, C33, C44, C66 (2*C66=C11-C12)
+            tetragonal: C11, C12, C13, C16, C33, C44, C66 (C16 optional)
+            rhombohedral: C11, C12, C13, C14, C15, C33, C44, C66 (2*C66=C11-C12, C15 optional)
+            orthorhombic: C11, C12, C13, C22, C23, C33, C44, C55, C66
+            monoclinic: C11, C12, C13, C15, C22, C23, C25, C33, C35, C44, C46, C55, C66
+            triclinic: all Cij where i <= j
+        M, Lame, mu, E, nu, K : float
+            Individual isotropic elastic moduli that can be used instead.
+        verify : bool, optional
+            Used with hexagonal and rhombohedral Cij sets.  If True (default) then values
+            of the non-independent moduli C11, C12, C66 will be checked for compatibility
+            if all three are given.
+        """
+        # Pop verify if needed
+        verify = kwargs.pop('verify', True)
+
+        # Initialize for no arguments
+        if len(kwargs) == 0:
+            self.__c_ij = np.zeros((6,6), dtype='float64')
+
+        # Initialize for matrix arguments
+        elif 'Cij' in kwargs:
+            assert len(kwargs) == 1, 'Cij cannot be specified with other keyword arguments'
+            self.Cij = kwargs['Cij']
+        elif 'Sij' in kwargs:
+            assert len(kwargs) == 1, 'Sij cannot be specified with other keyword arguments'
+            self.Sij = kwargs['Sij']
+        elif 'Cij9' in kwargs:
+            assert len(kwargs) == 1, 'Cij9 cannot be specified with other keyword arguments'
+            self.Cij9 = kwargs['Cij9']
+        elif 'Cijkl' in kwargs:
+            assert len(kwargs) == 1, 'Cijkl cannot be specified with other keyword arguments'
+            self.Cijkl = kwargs['Cijkl']
+        elif 'Sijkl' in kwargs:
+            assert len(kwargs) == 1, 'Sijkl cannot be specified with other keyword arguments'
+            self.Sijkl = kwargs['Sijkl']
+
+        # Initialize using data model
+        elif 'model' in kwargs:
+            self.model(**kwargs)
+
+        # Initialize for individually specified parameters by standard representation
+        elif ('C24' in kwargs or 'C26' in kwargs or 'C34' in kwargs or
+              'C36' in kwargs or 'C45' in kwargs or 'C56' in kwargs):
+            self.triclinic(**kwargs)
+        elif 'C25' in kwargs or 'C35' in kwargs or 'C46' in kwargs:
+            self.monoclinic(**kwargs)
+        elif 'C22' in kwargs or 'C23' in kwargs or 'C55' in kwargs:
+            self.orthorhombic(**kwargs)
+        elif 'C14' in kwargs:
+            self.rhombohedral(verify=verify, **kwargs)
+        elif 'C13' in kwargs or 'C33' in kwargs or 'C66' in kwargs:
+            if 'C16' in kwargs or ('C11' in kwargs and 'C12' in kwargs and 'C66' in kwargs):
+                self.tetragonal(**kwargs)
+            else:
+                self.hexagonal(verify=verify, **kwargs)
+        elif len(kwargs) == 3:
+            self.cubic(**kwargs)
+        elif len(kwargs) == 2:
+            self.isotropic(**kwargs)
+        else:
+            raise TypeError('Invalid argument keywords')
+
+    def __str__(self)  -> str:
+        """Calling string returns str(self.Cij)."""
+        return str(self.Cij)
+
+    @property
+    def Cij(self) -> np.ndarray:
+        """The stiffness constants in Voigt 6x6 format"""
+        return deepcopy(self.__c_ij)
+
+    @Cij.setter
+    def Cij(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype='float64')
+        assert value.shape == (6,6),  'Cij must be 6x6'
+
+        # Zero out near-zero terms
+        assert value.max() > 0.0, 'Cij values not valid'
+        value[np.isclose(value/value.max(), 0.0, atol=1e-9)] = 0.0
+
+        # Check symmetry
+        for i in range(6):
+            for j in range(i):
+                assert np.isclose(value[i,j], value[j,i], atol=1e-9), '6x6 matrix not symmetric!'
+        self.__c_ij = value
+
+    @property
+    def Sij(self) -> np.ndarray:
+        """The compliance constants in Voigt 6x6 format"""
+        return np.linalg.inv(self.Cij)
+
+    @Sij.setter
+    def Sij(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype='float64')
+        assert value.shape == (6,6),  'Sij must be 6x6'
+        self.Cij = np.linalg.inv(value)
+
+    @property
+    def Cij9(self) -> np.ndarray:
+        """The stiffness constants in 9x9 format"""
+        c = self.Cij
+        return np.array([[c[0,0],c[0,1],c[0,2],c[0,3],c[0,4],c[0,5],c[0,3],c[0,4],c[0,5]],
+                         [c[1,0],c[1,1],c[1,2],c[1,3],c[1,4],c[1,5],c[1,3],c[1,4],c[1,5]],
+                         [c[2,0],c[2,1],c[2,2],c[2,3],c[2,4],c[2,5],c[2,3],c[2,4],c[2,5]],
+                         [c[3,0],c[3,1],c[3,2],c[3,3],c[3,4],c[3,5],c[3,3],c[3,4],c[3,5]],
+                         [c[4,0],c[4,1],c[4,2],c[4,3],c[4,4],c[4,5],c[4,3],c[4,4],c[4,5]],
+                         [c[5,0],c[5,1],c[5,2],c[5,3],c[5,4],c[5,5],c[5,3],c[5,4],c[5,5]],
+                         [c[3,0],c[3,1],c[3,2],c[3,3],c[3,4],c[3,5],c[3,3],c[3,4],c[3,5]],
+                         [c[4,0],c[4,1],c[4,2],c[4,3],c[4,4],c[4,5],c[4,3],c[4,4],c[4,5]],
+                         [c[5,0],c[5,1],c[5,2],c[5,3],c[5,4],c[5,5],c[5,3],c[5,4],c[5,5]]])
+
+    @Cij9.setter
+    def Cij9(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype='float64')
+        assert value.shape == (9,9), 'Cij9 must be 9x9'
+
+        # Check symmetry
+        for i in range(6, 9):
+            for j in range(9):
+                assert value[i,j] == value[i-3, j]
+                assert value[j,i] == value[j, i-3]
+        self.Cij = value[:6, :6]
+
+    @property
+    def Cijkl(self) -> np.ndarray:
+        """The stiffness constants in 3x3x3x3 format"""
+        c = self.Cij
+        return np.array([[[[c[0,0],c[0,5],c[0,4]], [c[0,5],c[0,1],c[0,3]], [c[0,4],c[0,3],c[0,2]]],
+                          [[c[5,0],c[5,5],c[5,4]], [c[5,5],c[5,1],c[5,3]], [c[5,4],c[5,3],c[5,2]]],
+                          [[c[4,0],c[4,5],c[4,4]], [c[4,5],c[4,1],c[4,3]], [c[4,4],c[4,3],c[4,2]]]],
+
+                         [[[c[5,0],c[5,5],c[5,4]], [c[5,5],c[5,1],c[5,3]], [c[5,4],c[5,3],c[5,2]]],
+                          [[c[1,0],c[1,5],c[1,4]], [c[1,5],c[1,1],c[1,3]], [c[1,4],c[1,3],c[1,2]]],
+                          [[c[3,0],c[3,5],c[3,4]], [c[3,5],c[3,1],c[3,3]], [c[3,4],c[3,3],c[3,2]]]],
+
+                         [[[c[4,0],c[4,5],c[4,4]], [c[4,5],c[4,1],c[4,3]], [c[4,4],c[4,3],c[4,2]]],
+                          [[c[3,0],c[3,5],c[3,4]], [c[3,5],c[3,1],c[3,3]], [c[3,4],c[3,3],c[3,2]]],
+                          [[c[2,0],c[2,5],c[2,4]], [c[2,5],c[2,1],c[2,3]], [c[2,4],c[2,3],c[2,2]]]]])
+
+    @Cijkl.setter
+    def Cijkl(self, value: npt.ArrayLike):
+        c = np.asarray(value, dtype='float64')
+        assert c.shape == (3,3,3,3),  'Cijkl must be 3x3x3x3'
+        assert c.max() > 0.0, 'Cij values not valid'
+        # Check symmetry
+        indexes = np.array([[0,0], [1,1], [2,2], [1,2], [0,2], [0,1]], dtype=int)
+        for ij in range(6):
+            for kl in range(ij, 6):
+                i, j, k, l = indexes[ij,0], indexes[ij,1], indexes[kl,0], indexes[kl,1]
+                assert np.isclose(c[i,j,k,l], c[j,i,k,l])
+                assert np.isclose(c[i,j,k,l], c[j,i,l,k])
+                assert np.isclose(c[i,j,k,l], c[k,l,j,i])
+                assert np.isclose(c[i,j,k,l], c[l,k,j,i])
+                assert np.isclose(c[i,j,k,l], c[i,j,l,k])
+                assert np.isclose(c[i,j,k,l], c[k,l,i,j])
+                assert np.isclose(c[i,j,k,l], c[l,k,i,j])
+
+        self.Cij = np.array([[c[0,0,0,0], c[0,0,1,1], c[0,0,2,2], c[0,0,1,2], c[0,0,0,2], c[0,0,0,1]],
+                             [c[1,1,0,0], c[1,1,1,1], c[1,1,2,2], c[1,1,1,2], c[1,1,0,2], c[1,1,0,1]],
+                             [c[2,2,0,0], c[2,2,1,1], c[2,2,2,2], c[2,2,1,2], c[2,2,0,2], c[2,2,0,1]],
+                             [c[1,2,0,0], c[1,2,1,1], c[1,2,2,2], c[1,2,1,2], c[1,2,0,2], c[1,2,0,1]],
+                             [c[0,2,0,0], c[0,2,1,1], c[0,2,2,2], c[0,2,1,2], c[0,2,0,2], c[0,2,0,1]],
+                             [c[0,1,0,0], c[0,1,1,1], c[0,1,2,2], c[0,1,1,2], c[0,1,0,2], c[0,1,0,1]]])
+
+    @property
+    def Sijkl(self) -> np.ndarray:
+        """The compliance constants in 3x3x3x3 format"""
+        s = self.Sij
+        s[3:,:] = s[3:,:]/2.
+        s[:,3:] = s[:,3:]/2.
+        return np.array([[[[s[0,0],s[0,5],s[0,4]], [s[0,5],s[0,1],s[0,3]], [s[0,4],s[0,3],s[0,2]]],
+                          [[s[5,0],s[5,5],s[5,4]], [s[5,5],s[5,1],s[5,3]], [s[5,4],s[5,3],s[5,2]]],
+                          [[s[4,0],s[4,5],s[4,4]], [s[4,5],s[4,1],s[4,3]], [s[4,4],s[4,3],s[4,2]]]],
+
+                         [[[s[5,0],s[5,5],s[5,4]], [s[5,5],s[5,1],s[5,3]], [s[5,4],s[5,3],s[5,2]]],
+                          [[s[1,0],s[1,5],s[1,4]], [s[1,5],s[1,1],s[1,3]], [s[1,4],s[1,3],s[1,2]]],
+                          [[s[3,0],s[3,5],s[3,4]], [s[3,5],s[3,1],s[3,3]], [s[3,4],s[3,3],s[3,2]]]],
+
+                         [[[s[4,0],s[4,5],s[4,4]], [s[4,5],s[4,1],s[4,3]], [s[4,4],s[4,3],s[4,2]]],
+                          [[s[3,0],s[3,5],s[3,4]], [s[3,5],s[3,1],s[3,3]], [s[3,4],s[3,3],s[3,2]]],
+                          [[s[2,0],s[2,5],s[2,4]], [s[2,5],s[2,1],s[2,3]], [s[2,4],s[2,3],s[2,2]]]]])
+
+    @Sijkl.setter
+    def Sijkl(self, value: npt.ArrayLike):
+        s = np.asarray(value, dtype='float64')
+        assert s.shape == (3,3,3,3),  'Sijkl must be 3x3x3x3'
+
+        # Check symmetry
+        indexes = np.array([[0,0], [1,1], [2,2], [1,2], [0,2], [0,1]], dtype=int)
+        for ij in range(6):
+            for kl in range(ij, 6):
+                i, j, k, l = indexes[ij,0], indexes[ij,1], indexes[kl,0], indexes[kl,1]
+                assert np.isclose(s[i,j,k,l], s[j,i,k,l])
+                assert np.isclose(s[i,j,k,l], s[j,i,l,k])
+                assert np.isclose(s[i,j,k,l], s[k,l,j,i])
+                assert np.isclose(s[i,j,k,l], s[l,k,j,i])
+                assert np.isclose(s[i,j,k,l], s[i,j,l,k])
+                assert np.isclose(s[i,j,k,l], s[k,l,i,j])
+                assert np.isclose(s[i,j,k,l], s[l,k,i,j])
+
+        self.Sij = np.array([[   s[0,0,0,0],    s[0,0,1,1],    s[0,0,2,2], 2.*s[0,0,1,2], 2.*s[0,0,0,2], 2.*s[0,0,0,1]],
+                             [   s[1,1,0,0],    s[1,1,1,1],    s[1,1,2,2], 2.*s[1,1,1,2], 2.*s[1,1,0,2], 2.*s[1,1,0,1]],
+                             [   s[2,2,0,0],    s[2,2,1,1],    s[2,2,2,2], 2.*s[2,2,1,2], 2.*s[2,2,0,2], 2.*s[2,2,0,1]],
+                             [2.*s[1,2,0,0], 2.*s[1,2,1,1], 2.*s[1,2,2,2], 4.*s[1,2,1,2], 4.*s[1,2,0,2], 4.*s[1,2,0,1]],
+                             [2.*s[0,2,0,0], 2.*s[0,2,1,1], 2.*s[0,2,2,2], 4.*s[0,2,1,2], 4.*s[0,2,0,2], 4.*s[0,2,0,1]],
+                             [2.*s[0,1,0,0], 2.*s[0,1,1,1], 2.*s[0,1,2,2], 4.*s[0,1,1,2], 4.*s[0,1,0,2], 4.*s[0,1,0,1]]])
+
+    def transform(self,
+                  axes: npt.ArrayLike,
+                  tol: float = 1e-8) -> ElasticConstants2:
+        """
+        Transforms the elastic constant matrix based on the supplied axes.
+        
+        Parameters
+        ----------
+        axes : numpy.ndarray
+            (3, 3) array giving three right-handed orthogonal vectors to use
+            for transforming.
+        tol : float, optional
+            Relative tolerance to use in identifying near-zero terms.
+            
+        Returns
+        -------
+        ElasticConstants
+            A new ElasticConstants object that has been transformed.
+        """
+        axes = np.asarray(axes, dtype='float64')
+        T = axes_check(axes)
+
+        Q = np.einsum('km,ln->mnkl', T, T)
+        C = np.einsum('ghij,ghmn,mnkl->ijkl', Q, self.Cijkl, Q)
+        C[abs(C / C.max()) < tol] = 0.0
+
+        return ElasticConstants2(Cijkl=C)
+
+    def isotropic(self, *,
+                  C11: Optional[float] = None,
+                  C12: Optional[float] = None,
+                  C44: Optional[float] = None,
+                  M: Optional[float] = None,
+                  Lame: Optional[float] = None,
+                  mu: Optional[float] = None,
+                  E: Optional[float] = None,
+                  nu: Optional[float] = None,
+                  K: Optional[float] = None):
+        """
+        Set values with two independent isotropic moduli.
+        
+        Parameters
+        ----------
+        C11 : float, optional
+            C11 component of Cij.
+        C12 : float, optional
+            C12 component of Cij.
+        C44 : float, optional
+            C44 component of Cij.
+        M : float, optional
+            P-wave modulus(Equivalent to C11).
+        Lame : float, optional
+            Lame's first parameter (Equivalent to C12).
+        mu : float, optional
+            Shear modulus (Equivalent to C44).
+        E : float, optional
+            Young's modulus
+        nu : float, optional
+            Poisson's ratio
+        K : float, optional
+            Bulk modulus
+        """
+        # Count moduli with values
+        kwargcount = sum([C11 is not None, C12 is not None, C44 is not None,
+                          M is not None, Lame is not None, mu is not None,
+                          E is not None, nu is not None, K is not None])
+        if kwargcount != 2:
+            raise TypeError('isotropic requires exactly two independent moduli')
+
+        # Handle equivalent terms
+        if M is not None:
+            if C11 is not None:
+                raise ValueError('C11 and M are not independent moduli')
+            C11 = M
+        if Lame is not None:
+            if C12 is not None:
+                raise ValueError('C12 and Lame are not independent moduli')
+            C12 = Lame
+        if mu is not None:
+            if C44 is not None:
+                raise ValueError('C44 and mu are not independent moduli')
+            C44 = mu
+
+        # C11 + (something) combinations
+        if C11 is not None:
+
+            # Get C44 from C11 and C12
+            if C12 is not None:
+                C44 = (C11 - C12) / 2
+
+            # Find C44 then get C12
+            else:
+                if E is not None:
+                    S = (E**2 + 9 * C11**2 - 10 * E * C11)**0.5
+                    C44 = (3 * C11 + E - S) / 8
+                elif nu is not None:
+                    C44 = C11 * (1 - 2 * nu) / (2 * (1 - nu))
+                elif K is not None:
+                    C44 = 3 * (C11 - K) / 4
+                # else: C44 is not None
+
+                C12 = C11 - 2 * C44
+
+        # Combinations without C11: find C12 and C44 then get C11
+        else:
+            # C12 + (something) combinations
+            if C12 is not None:
+                if E is not None:
+                    R = (E**2 + 9 * C12**2 + 2 * E * C12)**0.5
+                    C44 = (E - 3 * C12 + R) / 4
+                elif nu is not None:
+                    C44 = C12 * (1 - 2 * nu) / (2 * nu)
+                elif K is not None:
+                    C44 = 3 * (K - C12) / 2
+                # else: C44 is not None
+
+            # C44 + (something) combinations
+            elif C44 is not None:
+                if E is not None:
+                    C12 = C44 * (E - 2 * C44) / (3 * C44 - E)
+                elif nu is not None:
+                    C12 = 2 * C44 * nu / (1 - 2 * nu)
+                else: # K is not None
+                    C12 = K - 2 * C44 / 3
+
+            # Others + (something) combinations
+            elif E is not None:
+                if nu is not None:
+                    C12 = E * nu / ((1 + nu) * (1 - 2 * nu))
+                    C44 = E / (2 * (1 + nu))
+                else: # K is not None
+                    C12 = 3 * K * (3 * K - E) / (9 * K - E)
+                    C44 = 3 * K * E / (9 * K - E)
+            elif nu is not None:
+                #if K is not None:
+                C12 = 3 * K * nu / (1 + nu)
+                C44 = 3 * K * (1 - 2 * nu) / (2 * (1 + nu))
+
+            C11 = C12 + 2 * C44
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C12, 0.0, 0.0, 0.0],
+                             [C12, C11, C12, 0.0, 0.0, 0.0],
+                             [C12, C12, C11, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, C44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, C44, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, C44]])
+
+    def cubic(self, *,
+              C11: Optional[float] = None,
+              C12: Optional[float] = None,
+              C44: Optional[float] = None):
+        """
+        Set values with three independent cubic moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        """
+        if C11 is None or C12 is None or C44 is None:
+            raise TypeError('cubic style requires C11, C12, and C66')
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C12, 0.0, 0.0, 0.0],
+                             [C12, C11, C12, 0.0, 0.0, 0.0],
+                             [C12, C12, C11, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, C44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, C44, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, C44]])
+
+    def hexagonal(self, *,
+                  C11: Optional[float] = None,
+                  C12: Optional[float] = None,
+                  C13: Optional[float] = None,
+                  C33: Optional[float] = None,
+                  C44: Optional[float] = None,
+                  C66: Optional[float] = None,
+                  verify: bool = True):
+        """
+        Set values with five independent hexagonal moduli.
+        (2 * C66 = C11 - C12)
+        
+        Parameters
+        ----------
+        C11 : float, optional
+            C11 component of Cij.
+        C12 : float, optional
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C66 : float, optional
+            C66 component of Cij.
+        verify : bool, optional
+            If True (default), the values of the non-independent moduli C11,
+            C12, and C66 will be checked for compatibility if all are given.
+        """
+        if C13 is None or C33 is None or C44 is None:
+            raise TypeError('hexagonal style requires C13, C33, and C44')
+
+        # Calculate missing C11, C12 or C66
+        if C11 is None:
+            if C12 is None or C66 is None:
+                raise TypeError('hexagonal style requires at least two of C11, C12, and C66')
+            C11 = 2 * C66 + C12
+        elif C12 is None:
+            if C66 is None:
+                raise TypeError('hexagonal style requires at least two of C11, C12, and C66')
+            C12 = C11 - 2 * C66
+        elif C66 is None:
+            C66 = (C11 - C12) / 2
+
+        # Verify 2 * C66 = C11 - C12
+        elif verify:
+            if not np.isclose(2 * C66, C11 - C12):
+                raise ValueError('dependent values not compatible: C11-C12 != 2*C66')
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C13, 0.0, 0.0, 0.0],
+                             [C12, C11, C13, 0.0, 0.0, 0.0],
+                             [C13, C13, C33, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, C44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, C44, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, C66]])
+
+    def rhombohedral(self, *,
+                     C11: Optional[float] = None,
+                     C12: Optional[float] = None,
+                     C13: Optional[float] = None,
+                     C14: Optional[float] = None,
+                     C15: float = 0.0,
+                     C33: Optional[float] = None,
+                     C44: Optional[float] = None,
+                     C66: Optional[float] = None,
+                     verify: bool = True):
+        """
+        Set values with six or seven independent rhombohedral moduli. 
+        (2 * C66 = C11 - C12)
+        
+        Parameters
+        ----------
+        C11 : float, optional
+            C11 component of Cij.
+        C12 : float, optional
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C14 : float
+            C14 component of Cij.
+        C15 : float, optional
+            C15 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C66 : float, optional
+            C66 component of Cij.
+        verify : bool, optional
+            If True, the values of the non-independent moduli C11, C12, C66
+            will be checked for compatibility.
+        """
+        if C13 is None or C14 is None or C33 is None or C44 is None:
+            raise TypeError('rhombohedral style requires C13, C14, C33, and C44')
+
+        # Calculate missing C11, C12 or C66
+        if C11 is None:
+            if C12 is None or C66 is None:
+                raise TypeError('rhombohedral style requires at least two of C11, C12, and C66')
+            C11 = 2 * C66 + C12
+        elif C12 is None:
+            if C66 is None:
+                raise TypeError('rhombohedral style requires at least two of C11, C12, and C66')
+            C12 = C11 - 2 * C66
+        elif C66 is None:
+            C66 = (C11 - C12) / 2
+
+        # Verify 2 * C66 = C11 - C12
+        elif verify:
+            if not np.isclose(2 * C66, C11 - C12):
+                raise ValueError('dependent values not compatible: C11-C12 != 2*C66')
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C13, C14, C15, 0.0],
+                             [C12, C11, C13,-C14,-C15, 0.0],
+                             [C13, C13, C33, 0.0, 0.0, 0.0],
+                             [C14,-C14, 0.0, C44, 0.0,-C15],
+                             [C15,-C15, 0.0, 0.0, C44, C14],
+                             [0.0, 0.0, 0.0,-C15, C14, C66]])
+
+    def tetragonal(self, *,
+                   C11: Optional[float] = None,
+                   C12: Optional[float] = None,
+                   C13: Optional[float] = None,
+                   C16: float = 0.0,
+                   C33: Optional[float] = None,
+                   C44: Optional[float] = None,
+                   C66: Optional[float] = None):
+        """
+        Set values with six or seven independent tetragonal moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C16 : float, optional
+            C16 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        if (C11 is None or C12 is None or C13 is None or
+            C33 is None or C44 is None or C66 is None):
+            raise TypeError('tetragonal style requires C11, C12, C13, C33, C44, and C66')
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C13, 0.0, 0.0, C16],
+                             [C12, C11, C13, 0.0, 0.0,-C16],
+                             [C13, C13, C33, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, C44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, C44, 0.0],
+                             [C16,-C16, 0.0, 0.0, 0.0, C66]])
+
+    def orthorhombic(self, *,
+                     C11: Optional[float] = None,
+                     C12: Optional[float] = None,
+                     C13: Optional[float] = None,
+                     C22: Optional[float] = None,
+                     C23: Optional[float] = None,
+                     C33: Optional[float] = None,
+                     C44: Optional[float] = None,
+                     C55: Optional[float] = None,
+                     C66: Optional[float] = None):
+        """
+        Set values with nine independent orthorhombic moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C22 : float
+            C22 component of Cij.
+        C23 : float
+            C23 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C55 : float
+            C55 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        if (C11 is None or C12 is None or C13 is None or
+            C22 is None or C23 is None or C33 is None or
+            C44 is None or C55 is None or C66 is None):
+            raise TypeError('orthorhombic style requires C11, C12, C13, C22, C23, C33, C44, C55, and C66')
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C13, 0.0, 0.0, 0.0],
+                             [C12, C22, C23, 0.0, 0.0, 0.0],
+                             [C13, C23, C33, 0.0, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, C44, 0.0, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, C55, 0.0],
+                             [0.0, 0.0, 0.0, 0.0, 0.0, C66]])
+
+    def monoclinic(self, *,
+                   C11: Optional[float] = None,
+                   C12: Optional[float] = None,
+                   C13: Optional[float] = None,
+                   C15: Optional[float] = None,
+                   C22: Optional[float] = None,
+                   C23: Optional[float] = None,
+                   C25: Optional[float] = None,
+                   C33: Optional[float] = None,
+                   C35: Optional[float] = None,
+                   C44: Optional[float] = None,
+                   C46: Optional[float] = None,
+                   C55: Optional[float] = None,
+                   C66: Optional[float] = None):
+        """
+        Set values with thirteen independent monoclinic moduli.
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C15 : float
+            C15 component of Cij.
+        C22 : float
+            C22 component of Cij.
+        C23 : float
+            C23 component of Cij.
+        C25 : float
+            C25 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C35 : float
+            C35 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C46 : float
+            C46 component of Cij.
+        C55 : float
+            C55 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        if (C11 is None or C12 is None or C13 is None or C15 is None or
+            C22 is None or C23 is None or C25 is None or
+            C33 is None or C35 is None or C44 is None or
+            C46 is None or C55 is None or C66 is None):
+            raise TypeError('monoclinic style requires C11, C12, C13, C15, C22, C23, C25, C33, C35, C44, C46, C55, and C66')
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C13, 0.0, C15, 0.0],
+                             [C12, C22, C23, 0.0, C25, 0.0],
+                             [C13, C23, C33, 0.0, C35, 0.0],
+                             [0.0, 0.0, 0.0, C44, 0.0, C46],
+                             [C15, C25, C35, 0.0, C55, 0.0],
+                             [0.0, 0.0, 0.0, C46, 0.0, C66]])
+
+    def triclinic(self, *,
+                  C11: Optional[float] = None,
+                  C12: Optional[float] = None,
+                  C13: Optional[float] = None,
+                  C14: Optional[float] = None,
+                  C15: Optional[float] = None,
+                  C16: Optional[float] = None,
+                  C22: Optional[float] = None,
+                  C23: Optional[float] = None,
+                  C24: Optional[float] = None,
+                  C25: Optional[float] = None,
+                  C26: Optional[float] = None,
+                  C33: Optional[float] = None,
+                  C34: Optional[float] = None,
+                  C35: Optional[float] = None,
+                  C36: Optional[float] = None,
+                  C44: Optional[float] = None,
+                  C45: Optional[float] = None,
+                  C46: Optional[float] = None,
+                  C55: Optional[float] = None,
+                  C56: Optional[float] = None,
+                  C66: Optional[float] = None):
+        """
+        Set values with twenty one independent triclinic moduli
+        
+        Parameters
+        ----------
+        C11 : float
+            C11 component of Cij.
+        C12 : float
+            C12 component of Cij.
+        C13 : float
+            C13 component of Cij.
+        C14 : float
+            C14 component of Cij.
+        C15 : float
+            C15 component of Cij.
+        C16 : float
+            C16 component of Cij.
+        C22 : float
+            C22 component of Cij.
+        C23 : float
+            C23 component of Cij.
+        C24 : float
+            C24 component of Cij.
+        C25 : float
+            C25 component of Cij.
+        C26 : float
+            C26 component of Cij.
+        C33 : float
+            C33 component of Cij.
+        C34 : float
+            C34 component of Cij.
+        C35 : float
+            C35 component of Cij.
+        C36 : float
+            C36 component of Cij.
+        C44 : float
+            C44 component of Cij.
+        C45 : float
+            C45 component of Cij.
+        C46 : float
+            C46 component of Cij.
+        C55 : float
+            C55 component of Cij.
+        C56 : float
+            C56 component of Cij.
+        C66 : float
+            C66 component of Cij.
+        """
+        if (C11 is None or C12 is None or C13 is None or
+            C14 is None or C15 is None or C16 is None or
+            C22 is None or C23 is None or C24 is None or
+            C25 is None or C26 is None or C33 is None or
+            C34 is None or C35 is None or C36 is None or
+            C44 is None or C45 is None or C46 is None or
+            C55 is None or C56 is None or C66 is None):
+            raise TypeError('triclinic style requires all 6x6 Cij where i <= j')
+
+        # Build Cij array
+        self.Cij = np.array([[C11, C12, C13, C14, C15, C16],
+                             [C12, C22, C23, C24, C25, C26],
+                             [C13, C23, C33, C34, C35, C36],
+                             [C14, C24, C34, C44, C45, C46],
+                             [C15, C25, C35, C45, C55, C56],
+                             [C16, C26, C36, C46, C56, C66]])
+
+    def normalized_as(self,
+                      crystal_system: str,
+                      return_dict: bool = False
+                      ) -> Union[dict, ElasticConstants2]:
+        """
+        Returns a new ElasticConstants object where values of the current are
+        averaged or zeroed out according to a standard crystal system setting.
+        NOTE: no validation checks are made to evaluate whether such
+        normalizations should be done! That is left up to you (compare values
+        before and after normalization).
+        
+        Parameters
+        ----------
+        crystal_system : str
+            Indicates the crystal system representation to use when building a
+            data model.
+        return_dict: bool, optional
+            If False (default), a new ElasticConstants object will be returned.
+            If set to True, a dict containing only the unique lattice constants
+            for the crystal_system will be returned.
+            
+        Returns
+        -------
+        atomman.ElasticConstants
+            The elastic constants normalized according to the crystal system
+            symmetries. Returned if return_dict is False.
+        dict
+            A dict containing only the unique elastic constants for the given 
+            crystal_system.  For 'isotropic', mu and K are used.  For all
+            others, the unique Cij values will be used
+        """
+
+        c = self.Cij
+        c_dict = {}
+
+        if crystal_system == 'isotropic':
+            c_dict['mu'] = self.shear()
+            c_dict['K'] = self.bulk()
+
+        elif crystal_system == 'cubic':
+            c_dict['C11'] = (c[0,0] + c[1,1] + c[2,2]) / 3
+            c_dict['C12'] = (c[0,1] + c[0,2] + c[1,2]) / 3
+            c_dict['C44'] = (c[3,3] + c[4,4] + c[5,5]) / 3
+
+        elif crystal_system == 'hexagonal':
+            c_dict['C11'] = (c[0,0] + c[1,1]) / 2
+            c_dict['C33'] = c[2,2]
+            c_dict['C12'] = (c[0,1] + (c[0,0] - 2*c[5,5])) / 2
+            c_dict['C13'] = (c[0,2] + c[1,2]) / 2
+            c_dict['C44'] = (c[3,3] + c[4,4]) / 2
+
+        elif crystal_system == 'tetragonal':
+            c_dict['C11'] = (c[0,0] + c[1,1]) / 2
+            c_dict['C33'] = c[2,2]
+            c_dict['C12'] = c[0,1]
+            c_dict['C13'] = (c[0,2] + c[1,2]) / 2
+            c_dict['C16'] = (c[0,5] - c[1,5]) / 2
+            c_dict['C44'] = (c[3,3] + c[4,4]) / 2
+            c_dict['C66'] = c[5,5]
+
+        elif crystal_system == 'rhombohedral':
+            c_dict['C11'] = (c[0,0] + c[1,1]) / 2
+            c_dict['C33'] = c[2,2]
+            c_dict['C12'] = (c[0,1] + (c[0,0] - 2*c[5,5])) / 2
+            c_dict['C13'] = (c[0,2] + c[1,2]) / 2
+            c_dict['C14'] = (c[0,3] - c[1,3]) / 2
+            c_dict['C15'] = (c[0,4] - c[1,4] - c[3,5]) / 3
+            c_dict['C44'] = (c[3,3] + c[4,4]) / 2
+
+        elif crystal_system == 'orthorhombic':
+            c_dict['C11'] = c[0,0]
+            c_dict['C22'] = c[1,1]
+            c_dict['C33'] = c[2,2]
+            c_dict['C12'] = c[0,1]
+            c_dict['C13'] = c[0,2]
+            c_dict['C23'] = c[1,2]
+            c_dict['C44'] = c[3,3]
+            c_dict['C55'] = c[4,4]
+            c_dict['C66'] = c[5,5]
+
+        elif crystal_system == 'monoclinic':
+            c_dict['C11'] = c[0,0]
+            c_dict['C22'] = c[1,1]
+            c_dict['C33'] = c[2,2]
+            c_dict['C12'] = c[0,1]
+            c_dict['C13'] = c[0,2]
+            c_dict['C15'] = c[0,4]
+            c_dict['C23'] = c[1,2]
+            c_dict['C25'] = c[1,4]
+            c_dict['C35'] = c[2,4]
+            c_dict['C46'] = c[3,5]
+            c_dict['C44'] = c[3,3]
+            c_dict['C55'] = c[4,4]
+            c_dict['C66'] = c[5,5]
+
+        elif crystal_system == 'triclinic':
+            c_dict['Cij'] = c
+
+        else:
+            raise ValueError('Invalid crystal_system: ' + crystal_system)
+
+        if return_dict:
+            return c_dict
+        return ElasticConstants2(**c_dict)
+
+    def is_normal(self,
+                  crystal_system: str,
+                  atol: float = 1e-4,
+                  rtol: float = 1e-4) -> bool:
+        """
+        Checks if current elastic constants agree with values normalized to
+        a specified crystal family (within tolerances).
+        
+        Parameters
+        ----------
+        crystal_system : str
+            Indicates the crystal system representation to use when building a
+            data model.
+        atol : float, optional
+            Absolute tolerance to use.  Default value is 1e-4.
+        rtol : float, optional
+            Relative tolerance to use.  Default value is 1e-4.
+        
+        Returns
+        -------
+        bool
+            True if all Cij match within the tolerances, false otherwise.
+        """
+        return np.allclose(self.Cij, self.normalized_as(crystal_system).Cij,
+                           atol=atol, rtol=rtol)
+
+    def model(self,
+              model: Union[str, io.IOBase, DM, None] = None,
+              unit: Optional[str] = None,
+              crystal_system: str = 'triclinic') -> Optional[DM]:
+        """
+        Return or set DataModelDict representation of the elastic constants.
+        
+        Parameters
+        ----------
+        model : DataModelDict, string, or file-like object, optional
+            Data model containing exactly one 'elastic-constants' branch to
+            read.
+        unit : str, optional
+            Units or pressure to save values in when building a data model.
+            Default value is None (no conversion).
+        crystal_system : str, optional
+            Indicates the crystal system representation to normalize by.
+            Default value is 'triclinic', i.e. no normalization.
+        
+        Returns
+        -------
+        DataModelDict
+            If model is not given as a parameter.
+        """
+
+        # Set values if model given
+        if model is not None:
+
+            # Find elastic-constants element
+            model = DM(model).find('elastic-constants')
+
+            # Read in values
+            if 'Cij' in model:
+                # New format
+                self.Cij = uc.value_unit(model['Cij'])
+            else:
+                # Old format
+                c_dict = {}
+                for C in model['C']:
+                    key = 'C' + C['ij'][0] + C['ij'][2]
+                    c_dict[key] = uc.value_unit(C['stiffness'])
+                self.Cij = ElasticConstants2(**c_dict).Cij
+
+        # Return DataModelDict if model not given
+        else:
+            normCij = self.normalized_as(crystal_system).Cij
+            model = DM()
+            model['elastic-constants'] = DM()
+            model['elastic-constants']['Cij'] = uc.model(normCij, unit)
+
+            return model
+
+    def bulk(self, style: str = 'Hill') -> float:
+        """
+        Returns a bulk modulus estimate.
+        
+        Parameters
+        ----------
+        style : str
+            Indicates which style of estimate to use.  Default value is 'Hill'.
+            - 'Hill' -- Hill estimate (average of Voigt and Reuss).
+            - 'Voigt' -- Voigt estimate. Uses Cij.
+            - 'Reuss' -- Reuss estimate. Uses Sij.
+        """
+        if style == 'Hill':
+            return (self.bulk('Voigt') + self.bulk('Reuss')) / 2
+
+        elif style == 'Voigt':
+            c = self.Cij
+            return ( (c[0,0] + c[1,1] + c[2,2]) + 2*(c[0,1] + c[1,2] + c[0,2]) ) / 9
+
+        elif style == 'Reuss':
+            s = self.Sij
+            return 1 / ( (s[0,0] + s[1,1] + s[2,2]) + 2*(s[0,1] + s[1,2] + s[0,2]) )
+
+        else:
+            raise ValueError('Unknown estimate style')
+
+    def shear(self, style: str = 'Hill') -> float:
+        """
+        Returns a shear modulus estimate.
+        
+        Parameters
+        ----------
+        style : str
+            Indicates which style of estimate to use.  Default value is 'Hill'.
+            - 'Hill' -- Hill estimate (average of Voigt and Reuss).
+            - 'Voigt' -- Voigt estimate. Uses Cij.
+            - 'Reuss' -- Reuss estimate. Uses Sij.
+        """
+        if style == 'Hill':
+            return (self.shear('Voigt') + self.shear('Reuss')) / 2
+
+        elif style == 'Voigt':
+            c = self.Cij
+            return ( (c[0,0] + c[1,1] + c[2,2]) - (c[0,1] + c[1,2] + c[0,2]) + 3*(c[3,3] + c[4,4] + c[5,5]) ) / 15
+
+        elif style == 'Reuss':
+            s = self.Sij
+            return 15 / ( 4*(s[0,0] + s[1,1] + s[2,2]) - 4*(s[0,1] + s[1,2] + s[0,2]) + 3*(s[3,3] + s[4,4] + s[5,5]) )
+
+        else:
+            raise ValueError('Unknown estimate style')

atomman/source/atomman/core/NeighborList.py

@@ -0,0 +1,263 @@
+# coding: utf-8
+
+# Standard Python imports
+import io
+from typing import Union, Optional
+
+# http://www.numpy.org/
+import numpy as np
+
+# atomman imports
+from .nlist import nlist
+from ..tools import uber_open_rmode
+
+class NeighborList(object):
+    """Class that finds and stores the neighbor atoms for a system."""
+    
+    def __init__(self, **kwargs):
+        """
+        Class initializer.  Calls NeighborList.load() if
+        'model' is given, otherwise calls NeighborList.build().
+        
+        Parameters
+        ----------
+        system : atomman.System, optional
+            The system to calculate the neighbor list for. Must be given if
+            model is not given.
+        cutoff : float, optional
+            Radial cutoff distance for identifying neighbors.  Must be given if
+            model is not given.
+        model : str or file-like object, optional
+            Gives the file path or content to load.  If given, no other
+            parameters are allowed.
+        initialsize : int, optional
+            The number of neighbor positions to initially assign to each atom.
+            Default value is 20.
+        deltasize : int, optional
+            Specifies the number of extra neighbor positions to allow each atom
+            when the number of neighbors exceeds the underlying array size.
+            Default value is 10.
+        nlist : array-like object, optional
+            An array consisting of int values, where each row is associated with
+            an atom, the first value in each row is that atom's coordination, and
+            all subsequent values (up to the coordination number) are indices of
+            the neighboring atoms.
+        """
+        # Load from model
+        if 'model' in kwargs:
+            model = kwargs.pop('model')
+            self.load(model, **kwargs)
+        
+        # Convert from existing nlist array
+        elif 'nlist' in kwargs:
+            nlist = kwargs.pop('nlist')
+            assert len(kwargs) == 0
+            self.__nlist = nlist
+            self.__coord = nlist[:, 0]
+            self.__neighbors = nlist[:, 1:]
+        
+        # Build new neighbor list
+        else:
+            system = kwargs.pop('system')
+            cutoff = kwargs.pop('cutoff')
+            self.build(system, cutoff, **kwargs)
+
+
+    @classmethod
+    def freud(cls,
+              system,
+              cutoff: Optional[float] = None,
+              coord: Optional[int] = None,
+              return_bonds: bool = False):
+        """
+        Use the AABBQuery from the freud Python package to build the neighbor
+        list.  This has better performance than the native atomman method and
+        allows for searching by number of neighbors, but requires additional
+        package installs. 
+
+        Parameters
+        ----------
+        system : atomman.System
+            The system to calculate the neighbor list for. 
+        cutoff : float, optional
+            Radial cutoff distance for identifying neighbors.  Either cutoff
+            or coord are required.
+        coord : int, optional
+            Number of neighbors to find for each atom.  Either cutoff
+            or coord are required.
+        return_bonds : bool, optional
+            If True, then the method will also return the list of bonds
+            found by the AABBQuery.  Useful if you also want the dmag vects
+            for all neighbor pairs.
+        """
+        try:
+            import freud
+        except ModuleNotFoundError as e:
+            raise ModuleNotFoundError('package freud must be installed for this method') from e
+        
+        # Build freud query terms dict
+        if cutoff is not None:
+            if coord is not None:
+                raise ValueError('cutoff and coord cannot both be given')
+            query_terms = dict(
+                mode = 'ball',
+                r_max = cutoff,
+                exclude_ii = True)
+            
+        elif coord is not None:
+            query_terms = dict(
+                mode = 'nearest',
+                num_neighbors = coord,
+                exclude_ii = True)
+        
+        else:
+            raise ValueError('either cutoff or coord must be given')
+
+        # Convert atomman system into freud box and points
+        box, points = system.dump('freud')
+
+        # Build query object and perform the query
+        aq = freud.locality.AABBQuery(box, points)      
+        bonds = aq.query(points, query_terms)
+        coord = 15
+        # Find max coord
+        if coord is None:
+            coord = 0       # coord is max coord across all atoms
+            last_i = -1
+            c = 0           # c is current coord count for atom i
+            for bond in bonds:
+                i, j, dmag = bond
+                if i != last_i:
+                    if c > coord:
+                        coord = c
+                    last_i = i
+                    c = 1
+                else:
+                    c += 1
+
+        # Build nlist
+        nlist = np.empty((system.natoms, coord+1), dtype=np.int64)
+        nlist[:, 0] = 0
+
+        for bond in bonds:
+            i, j, dmag = bond
+            
+            # Increase atom's coordination
+            nlist[i, 0] += 1
+            
+            # Add j to the nlist row
+            nlist[i, nlist[i, 0]] = j
+
+        # Initialize neighborlist object
+        neighbors = cls(nlist=nlist)
+
+        if return_bonds:
+            return neighbors, bonds
+        else:
+            return neighbors
+        
+
+    @property
+    def coord(self) -> np.ndarray:
+        """numpy.ndarray: The atomic coordination numbers"""
+        return self.__coord
+    
+    @property
+    def nlist(self) -> np.ndarray:
+        """numpy.ndarray: The underlying numpy array of coord + neighbor ids"""
+        return self.__nlist
+    
+    def __len__(self) -> int:
+        """len returns the number of atoms"""
+        return len(self.__coord)
+    
+    def __getitem__(self, key):
+        """Get returns the list of neighbors for the specified atom."""
+        return self.__neighbors[key, :self.coord[key]]
+    
+    def build(self,
+              system,
+              cutoff: float,
+              initialsize: int = 20,
+              deltasize: int = 10):
+        """
+        Builds the neighbor list for a system.
+        
+        Parameters
+        ----------
+        system : atomman.System 
+            The system to calculate the neighbor list for.
+        cutoff : float
+            Radial cutoff distance for identifying neighbors.
+        initialsize : int, optional
+            The number of neighbor positions to initially assign to each atom.
+            Default value is 20.
+        deltasize : int, optional
+            Specifies the number of extra neighbor positions to allow each atom
+            when the number of neighbors exceeds the underlying array size.
+            Default value is 10.
+        """
+        # Call nlist
+        self.__nlist = nlist(system, cutoff, initialsize=initialsize, 
+                             deltasize=deltasize)
+        
+        # Split coord and neighbors
+        self.__coord = self.__nlist[:, 0]
+        self.__neighbors = self.__nlist[:, 1:]
+        
+    def load(self, model: Union[str, io.IOBase]):
+        """
+        Read in a neighbor list from a file.
+        
+        Parameters
+        ----------
+        model : str or file-like object
+            Gives the file path or content to load.
+        """
+        # First pass determines number of atoms and max number of neighbors
+        nterms = 0
+        natoms = 0
+        with uber_open_rmode(model) as fin:
+            for line in fin:
+                line = line.decode('UTF-8')
+                terms = line.split()
+                n_n = len(terms)
+                if terms[0][0] != '#' and n_n > 0:
+                    natoms += 1
+                    if n_n > nterms:
+                        nterms = n_n
+            
+            self.__nlist = np.empty((natoms, nterms+1), dtype=int)
+            self.__coord = self.__nlist[:, 0]
+            self.__neighbors = self.__nlist[:, 1:]
+            
+            # Second pass gets values
+            self.__coord[:] = 0
+            fin.seek(0)
+            for line in fin:
+                line = line.decode('UTF-8')
+                terms = line.split()
+                if len(terms) > 0 and terms[0][0] != '#':
+                    i = int(terms[0])
+                    self.__coord[i] = len(terms) - 1
+                    for j in range(1, len(terms)):
+                        self.__neighbors[i, j-1] = terms[j]
+    
+    def dump(self, fname: str):
+        """
+        Saves the neighbor list to a file.
+        
+        Parameters
+        ----------
+        fname : str
+            The file name to save the content to.
+        """
+        with open(fname, 'w') as fp:
+            fp.write('# Neighbor list:\n')
+            fp.write('# The first column gives an atom index.\n')
+            fp.write('# The rest of the columns are the indexes of the identified neighbors.\n')
+            for i in range(len(self)):
+                fp.write('%i' % i)
+                for j in self[i]:
+                    fp.write(' %i' % j)
+                fp.write('\n')

atomman/source/atomman/core/System.py

@@ -0,0 +1,1267 @@
+# coding: utf-8
+# Standard Python libraries
+from __future__ import annotations
+import io
+from collections import OrderedDict
+from copy import deepcopy
+import warnings
+from typing import Any, Optional, Union, Tuple
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://pandas.pydata.org/
+import pandas as pd
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# atomman imports
+import atomman.unitconvert as uc
+from . import Atoms, Box, dvect, dmag, NeighborList
+from ..lammps import normalize as lmp_normalize
+from ..tools import indexstr, miller, ishexagonal, aslist
+from .. import dump
+
+class System(object):
+    """
+    A representation of an atomic system.  This combines Atoms with Box and
+    adds methods and attributes involving both.
+    """
+    
+    class _AtomsIndexer(object):
+        """Internal class for setitem / getitem acting on atoms"""
+        def __init__(self, host: System):
+            self.__host = host
+            
+        def __getitem__(self,
+                        index: Union[int, list, slice]) -> System:
+            """Index getting of Atoms that operates on System."""
+            host = self.__host
+            return System(atoms=host.atoms[index], box=host.box, pbc=host.pbc,
+                          symbols=host.symbols)
+            
+        def __setitem__(self,
+                        index: Union[int, list, slice],
+                        value: Any):
+            """Index setting of Atoms that operates on System."""
+            host = self.__host
+            if isinstance(value, Atoms):
+                host.atoms[index] = value
+            elif isinstance(value, System):
+                try:
+                    assert np.allclose(host.box.vects, value.box.vects)
+                    assert np.allclose(host.box.origin, value.box.origin)
+                except:
+                    warnings.warn('Atom assignment between two Systems with different boxes', UserWarning)
+                host.atoms[index] = value.atoms
+            else:
+                raise ValueError('Can only set using Atoms or System objects')
+    
+    def __init__(self,
+                 atoms: Optional[Atoms] = None,
+                 box: Optional[Box] = None,
+                 pbc: Optional[Tuple[bool, bool, bool]] = None,
+                 scale: bool = False,
+                 symbols: Union[str, list, None] = None,
+                 masses: Union[float, list, None] = None,
+                 model: Union[str, io.IOBase, DM, None] = None,
+                 safecopy: bool = False):
+        """
+        Initialize a System by joining an am.Atoms and am.Box instance.
+        
+        Parameters
+        ----------
+        atoms : atomman.Atoms, optional
+            The underlying Atoms object to build system around.
+        box : atomman.Box, optional
+            The underlying box object to build system around.
+        pbc : tuple or list of bool, optional
+            Indicates which of the dimensions related to the three box vectors
+            are periodic.  Default value is (True, True, True).
+        scale : bool, optional
+            If True, atoms.pos will be scaled relative to the box.  Default
+            value is False.
+        symbols : tuple, optional
+            A list of the element symbols for each atom atype.  If len(symbols)
+            is less than natypes, then missing values will be set to None.
+            Default sets list with all None values.
+        masses : tuple, optional
+            A list of the masses for each atom atype.  If len(symbols) is less
+            than natypes, then missing values will be set to None.  Default
+            sets list with all None values.
+        model : str or DataModelDict, optional
+            File path or content of a JSON/XML data model containing all
+            system information.  Cannot be given with atoms, box or scale.
+        safecopy : bool, optional
+            Flag indicating if values are to be copied before setting.  For
+            values given as objects, direct setting (False, default) may result
+            in the System pointing to the original object.  Using safecopy=True
+            deep copies the objects before setting to avoid this.  Note that
+            safecopy=True may be considerably slower for large numbers of atoms
+            and/or properties.
+        
+        Returns
+        =======
+        System
+            The System object.
+        """
+        # Check for model
+        if model is not None:
+            try:
+                assert atoms is None
+                assert box is None
+                assert scale is False
+            except:
+                raise ValueError('model cannot be given with atoms, box or scale parameters')
+            
+            # Load data model
+            model = DM(model).find('atomic-system')
+
+            # Extract values from model
+            box = Box(model=model)
+            atoms = Atoms(model=model)
+            if pbc is None:
+                pbc = model['periodic-boundary-condition']
+            if symbols is None:
+                symbols = tuple(model.aslist('atom-type-symbol'))
+            if masses is None:
+                masses = tuple(model.aslist('atom-type-mass'))
+
+        # Interpret given/missing parameters
+        else:
+            # Set default atoms or deepcopy
+            if atoms is None:
+                atoms = Atoms()
+            elif safecopy:
+                atoms = deepcopy(atoms)
+
+            # Set default box or deepcopy
+            if box is None:
+                box = Box()
+            elif safecopy:
+                box = deepcopy(box)
+            
+            # Set default pbc
+            if pbc is None:
+                pbc = (True, True, True)
+            
+            # Set default masses
+            if masses is None:
+                masses = []
+            else:
+                masses = aslist(masses)
+            
+            # Set default symbols
+            if symbols is None:
+                symbols = [None for i in range(len(masses))]
+            else:
+                symbols = aslist(symbols)
+            
+            # Check data types
+            if not isinstance(atoms, Atoms):
+                raise TypeError('Invalid atoms type')
+            if not isinstance(box, Box):
+                raise TypeError('Invalid box type')
+            if not isinstance(scale, bool):
+                raise TypeError('Invalid scale type')
+        
+        # Set properties
+        self.__atoms = atoms
+        self.__box = box
+        self.pbc = pbc
+        self.__transformation = np.identity(3)
+
+        self.symbols = symbols
+        self.masses = masses
+        
+        # Scale pos if needed
+        if scale is True:
+            self.atoms_prop('pos', value=self.atoms.pos, scale=True)
+        
+        # Scale model properties if needed
+        if model is not None:
+            for prop in model['atoms'].aslist('property'):
+                if prop['data'].get('unit', None) == 'scaled':
+                    self.atoms.view[prop['name']] = self.box.position_relative_to_cartesian(self.atoms.view[prop['name']]) 
+        
+        # Set atoms indexer
+        self.__atoms_ix = System._AtomsIndexer(self)
+    
+    def __str__(self) -> str:
+        """str : The string representation of a system."""
+        return '\n'.join([str(self.box),
+                          'natoms = ' + str(self.natoms),
+                          'natypes = ' + str(self.natypes),
+                          'symbols = ' + str(self.symbols),
+                          'pbc = ' + str(self.pbc),
+                          str(self.atoms)])
+    
+    def __len__(self) -> int:
+        return self.natoms
+    
+    @property
+    def atoms(self) -> Atoms:
+        """atomman.Atoms : underlying Atoms object."""
+        return self.__atoms
+    
+    @property
+    def natoms(self) -> int:
+        """int : The number of atoms in the Atoms class."""
+        return self.__atoms.natoms
+    
+    @property
+    def atypes(self) -> tuple:
+        """tuple : List of int atom types."""
+        return tuple(range(1, self.natypes+1))
+    
+    @property
+    def natypes(self) -> int:
+        """int : The number of atom types/symbols."""
+        
+        # Check if more symbols than atypes
+        try:
+            nsymbols = len(self.symbols)
+        except:
+            nsymbols = 0
+        if nsymbols > self.__atoms.natypes:
+            return len(self.symbols)
+        else:
+            return self.__atoms.natypes
+    
+    @property
+    def box(self) -> Box:
+        """atommman.Box : underlying Box object."""
+        return self.__box
+    
+    @property
+    def pbc(self) -> np.ndarray:
+        """numpy.ndarray of bool : The periodic boundary condition settings."""
+        return self.__pbc
+        
+    @pbc.setter
+    def pbc(self, value: npt.ArrayLike):
+        pbc = np.asarray(value, dtype=bool)
+        assert pbc.shape == (3,), 'invalid pbc entry' 
+        self.__pbc = pbc
+    
+    @property
+    def atoms_ix(self) -> _AtomsIndexer:
+        """Indexer for index slicing of Systems by per-atom properties."""
+        return self.__atoms_ix
+
+    @property
+    def symbols(self) -> tuple:
+        """tuple : The element model symbols associated with each atype."""
+        
+        # Fill in missing values
+        if len(self.__symbols) < self.__atoms.natypes:
+            self.symbols = self.__symbols
+        return self.__symbols
+    
+    @symbols.setter
+    def symbols(self, value: Union[str, list]):
+        
+        # Make value list if needed
+        value = aslist(value)
+        
+        # Fill in missing values
+        if len(value) < self.__atoms.natypes:
+            newvalue = [None for x in range(self.__atoms.natypes)]
+            for i in range(len(value)):
+                newvalue[i] = value[i]
+            value = newvalue
+
+        self.__symbols = tuple(value)
+
+    @property
+    def masses(self) -> tuple:
+        """tuple : The masses associated with each atype if given."""
+        
+        # Fill in missing values
+        if len(self.__masses) < self.natypes:
+            self.masses = self.__masses
+        return self.__masses
+    
+    @masses.setter
+    def masses(self, value: Union[float, list]):
+        
+        # Make value list if needed
+        value = aslist(value)
+        
+        # Convert non-None values to float
+        for i in range(len(value)):
+            if value[i] is not None:
+                value[i] = float(value[i])
+
+        # Fill in missing values
+        if len(value) < self.natypes:
+            newvalue = [None for x in range(self.natypes)]
+            for i in range(len(value)):
+                newvalue[i] = value[i]
+            value = newvalue
+        elif len(value) > self.natypes:
+            raise ValueError('More masses than atom types given. Either change atype values or symbols first.')
+
+        self.__masses = tuple(value)
+    
+    @property
+    def composition(self) -> Optional[str]:
+        """
+        The system's reduced and sorted symbols composition.
+        
+        Returns
+        -------
+        str or None
+            The system's reduced and sorted symbols composition.
+            Will return None if any symbols are missing
+        """
+        
+        # Build total count of each symbol
+        sym_dict = {}
+        for i in range(self.natypes):
+            count = np.sum(self.atoms.atype == i+1)
+            if count > 0:
+                symbol = self.symbols[i]
+                
+                if symbol is None:
+                    return None
+                
+                if symbol in sym_dict:
+                    sym_dict[symbol] += count
+                else:
+                    sym_dict[symbol] = count
+
+        # Find greatest common denominator
+        gcd = np.gcd.reduce(list(sym_dict.values())) # pylint: disable=no-member
+        
+        # Sort symbols and reduce counts
+        composition =''
+        for symbol in sorted(sym_dict):
+            count = sym_dict[symbol] // gcd
+            if sym_dict[symbol] > 0:
+                composition += symbol
+                if count != 1:
+                    composition += str(count)
+        
+        return composition
+    
+    def atoms_prop(self,
+                   key: Optional[str] = None,
+                   index: Union[int, list, slice, None] = None,
+                   value: Optional[Any] = None,
+                   a_id: Optional[int] = None,
+                   scale: bool = False
+                   ) -> Union[list, Atoms, np.ndarray, None]:
+        """
+        Extends Atoms.prop() by adding a scale argument.
+        
+        Parameters
+        ----------
+        key : str, optional
+            Per-atom property name.
+        index : int, list, slice, optional
+            Index of atoms.
+        value : any, optional
+            Property values to assign.
+        a_id : int, optional
+            Integer atom index.  Left in for backwards compatibility.
+        scale : bool, optional
+            Flag indicating if values should be scaled/unscaled. If True:
+            - Values being retrieved are scaled from absolute Cartesian to box relative vectors.
+            - Values being set are unscaled from box relative to absolute Cartesian vectors.
+            Default value is False.
+        
+        Returns
+        -------
+        list
+            If no parameters given, returns a list of all assigned property
+            keys.
+        atomman.Atoms
+            If index or a_id is given without value or key, returns a new
+            Atoms instance for the specified atom indices.
+        numpy.ndarray
+            If key (and index/a_id) is given without value, returns a copy of
+            the data associated with that property key.
+        """
+        
+        # Check that scale is bool
+        if not isinstance(scale, bool):
+            raise TypeError('Invalid scale type')
+        
+        # Call atoms.prop() for scale is False
+        if scale is False:
+            if value is None:
+                return self.atoms.prop(key=key, index=index, a_id=a_id)
+            else:
+                self.atoms.prop(key=key, index=index, value=value, a_id=a_id)
+        
+        # Handle property scaling if scale is True
+        else:
+            # Handle a_id
+            if a_id is not None:
+                if index is not None:
+                    raise ValueError('a_id and index cannot both be given')
+                index = a_id
+            
+            # Get values if value is None
+            if value is None:
+                # If no key, return copy of atoms (all or a slice) with scaled pos
+                if key is None:
+                    if index is None:
+                        newatoms = deepcopy(self.atoms)
+                    else:
+                        newatoms = deepcopy(self.atoms[index])
+                    newatoms.pos = self.box.position_cartesian_to_relative(newatoms.pos)
+                    return newatoms
+                
+                # If key is given, return scaled property values
+                else:
+                    if index is None:
+                        value = self.atoms.view[key]
+                    else:
+                        value = self.atoms.view[key][index]
+                    return self.box.position_cartesian_to_relative(value)
+            
+            # Set values if value is given
+            else:
+                # If no key, unscale pos of Atoms value and set to atoms (or a slice)
+                if key is None:
+                    if not isinstance(value, Atoms):
+                        raise TypeError('If key is None, value must be instance of atomman.Atoms')
+                    
+                    value.pos = self.box.position_relative_to_cartesian(value.pos)
+                    if index is None:
+                        self.atoms[:] = value
+                    else:
+                        self.atoms[index] = value
+                
+                # If key is given, unscale value and set to property
+                else:
+                    value = self.box.position_relative_to_cartesian(value)
+                    if index is None:
+                        self.atoms.view[key] = value
+                    else:
+                        self.atoms.view[key][index] = value
+    
+    def atoms_df(self,
+                 scale: bool = False) -> pd.DataFrame:
+        """
+        Extends Atoms.df() by adding a scale argument.
+        
+        Parameters
+        ----------
+        scale : bool or list, optional
+            Indicates if/which per-atom properties are to be scaled to box
+            relative values.  If False (default), no properties will be scaled.
+            If True, pos will be scaled.  Multiple properties can be scaled by
+            providing a list of the property names to scale.
+            
+        Returns
+        -------
+        pandas.DataFrame
+            Tabulated DataFrame version of the atomic data.
+        """
+        # Handle scale values
+        if scale is True:
+            scale = ['pos']
+        elif scale is False:
+            scale = []
+        elif not isinstance(scale, list):
+            scale = [scale]
+        
+        # Initialize new dictionary of values
+        values = OrderedDict()
+        for key in self.atoms.view.keys():
+            
+            value = self.atoms.view[key]
+            if key in scale:
+                value = self.box.position_cartesian_to_relative(value)
+            
+            # Flatten multidimensional arrays
+            for index, istr in indexstr(self.atoms.view[key].shape[1:]):
+                newkey = key + istr
+                
+                # Copy values over
+                if index == ():
+                    values[newkey] = value
+                else:
+                    values[newkey] = value[(Ellipsis, ) + index]
+        
+        # Return DataFrame
+        return pd.DataFrame(values)
+    
+    def atoms_extend(self,
+                     value: Union[Atoms, int],
+                     scale: bool = False,
+                     symbols: Optional[list] = None,
+                     safecopy: bool = False) -> System:
+        """
+        Extends Atoms.extend() to the System level by adding scale and symbols
+        arguments.
+        
+        Parameters
+        ----------
+        value : atomman.Atoms or int
+            An int value will result in the atoms object being extended by
+            that number of atoms, with all per-atom properties having default
+            values (atype = 1, everything else = 0).  For an Atoms value, the
+            current atoms list will be extended by the correct number of atoms
+            and all per-atom properties in value will be copied over.  Any
+            properties defined in one Atoms object and not the other will be
+            set to default values.
+        scale : bool, optional
+            Flag indicating if position values in a supplied Atoms value are to
+            be taken as absolute Cartesian (False, default) or in scaled box
+            relative units (True).
+        symbols : tuple, list or None, optional
+            Allows for the system's symbols list to be updated.  If not given,
+            will use the current object's symbols.
+        safecopy : bool, optional
+            Flag indicating if values are to be copied before setting.  If 
+            False (default), underlying objects may be shared between the new
+            system and the current system and input parameters.  If True, atoms
+            and box will be deepcopied before setting.
+            Note that safecopy=True may be considerably slower for large
+            numbers of atoms and/or properties.
+        
+        Returns
+        -------
+        atomman.System
+            A new System object with Atoms extended to contain all atoms and
+            properties of the current object plus the additional atoms.  The
+            current System object's box and pbc (and symbols if not specified)
+            will be copied over.
+        """
+        # Copy value if safecopy
+        if safecopy:
+            value = deepcopy(value)
+        
+        # scale only makes sense for Atoms values
+        if scale is True and not isinstance(value, Atoms):
+            raise ValueError('scale can only be True for Atoms values')        
+        
+        # Handle symbols parameter
+        if symbols is None:
+            symbols = self.symbols
+        
+        # Handle box
+        if safecopy:
+            box = deepcopy(self.box)
+        else:
+            box = self.box
+        
+        # Call atoms.extend to generate new atoms
+        atoms = self.atoms.extend(value)
+        
+        # Unscale pos from Atoms value if needed
+        if scale:
+            atoms.pos[value.natoms:] = self.box.position_relative_to_cartesian(value.pos)
+
+        # Generate and return new System
+        return System(atoms=atoms, box=box, pbc=self.pbc, symbols=symbols)
+    
+    def box_set(self, **kwargs):
+        """
+        Extends box.set() with a scale argument.
+        
+        Parameters
+        ----------
+        scale : bool
+            If True, the scaled (box-relative) positions remain unchanged.
+            Default value is False (absolute positions unchanged).
+        other kwargs : any
+            Any other kwargs allowed by box.set().
+        """
+        
+        # Pop scale
+        scale = kwargs.pop('scale', False)
+        if not isinstance(scale, bool):
+            raise TypeError('Invalid scale type')
+        
+        # Hold scaled positions constant
+        if scale is True:
+            spos = self.atoms_prop('pos', scale=True)
+            self.box.set(**kwargs)
+            self.atoms_prop('pos', value=spos, scale=True)
+        
+        # Call box.set without scaling
+        else:
+            self.box.set(**kwargs)
+    
+    def scale(self, value: npt.ArrayLike) -> np.ndarray:
+        """
+        Scales 3D vectors from absolute Cartesian coordinates to relative box
+        coordinates.
+        
+        Parameters
+        ----------
+        value : array-like object
+            Absolute Cartesian coordinates to scale.
+
+        Returns
+        -------
+        numpy.ndarray
+            The relative box coordinates associated with the given values.
+        """
+        warnmsg = "System.scale() will likely be depreciated in the next big version update "
+        warnmsg += "as the method name is not informative.  It is being replaced by the "
+        warnmsg += "equivalent Box.position_cartesian_to_relative() method."
+        warnings.warn(warnmsg, PendingDeprecationWarning)
+        
+        # Retrieve parameters
+        #value = np.asarray(value, dtype=float)
+        #vects = self.box.vects
+        #inverse = np.linalg.inv(vects)
+        #origin = self.box.origin
+        
+        # Convert
+        #return (value - origin).dot(inverse)
+
+        return self.box.position_cartesian_to_relative(value)
+
+    def unscale(self, value: npt.ArrayLike) -> np.ndarray:
+        """
+        Unscales 3D vectors from relative box coordinates to absolute
+        Cartesian coordinates.
+        
+        Parameters
+        ----------
+        value : numpy.ndarray
+            Relative box coordinates to unscale.
+
+        Returns
+        -------
+        numpy.ndarray
+            Absolute Cartesian coordinates associated with the given values.
+        """
+        warnmsg = "System.unscale() will likely be depreciated in the next big version update "
+        warnmsg += "as the method name is not informative.  It is being replaced by the "
+        warnmsg += "equivalent Box.position_relative_to_cartesian() method."
+        warnings.warn(warnmsg, PendingDeprecationWarning)
+        
+        # Retrieve parameters
+        #value = np.asarray(value, dtype=float)
+        #vects = self.box.vects
+        #origin = self.box.origin
+        
+        # Convert
+        #return value.dot(vects) + origin
+
+        return self.box.position_relative_to_cartesian(value)
+        
+    def wrap(self,
+             return_imageflags: bool = False) -> Optional[np.ndarray]:
+        """
+        Wrap atoms around periodic boundaries and extend non-periodic
+        boundaries such that all atoms are within the box.
+
+        Parameters
+        ----------
+        return_imageflags : bool, optional
+            If True, an array of which image the atom was originally in is
+            returned.
+
+        Returns
+        -------
+        numpy.NDarray of int
+            The imageflags array - only returned if return_imageflags = True.
+        """
+        
+        # mins and maxs are box dimensions relative to box vectors, i.e 0 to 1
+        mins = np.array([0.0, 0.0, 0.0])
+        maxs = np.array([1.0, 1.0, 1.0])
+        
+        # Retrieve scaled pos
+        spos = self.atoms_prop('pos', scale=True)
+
+        # Initialize wrapflags
+        imageflags = np.zeros_like(spos, dtype=int)
+        
+        # Loop over three pbc directions
+        for i in range(3):
+            
+            # Count wraps across periodic boundaries
+            if self.pbc[i]:
+                imageflags[:, i] = np.floor(spos[:, i]) # pylint: disable=unsupported-assignment-operation
+            
+            # Shift min and max to encompass atoms across non-periodic bounds
+            else:
+                min = spos[:, i].min()
+                max = spos[:, i].max()
+                if min <= mins[i]: 
+                    mins[i] = min - 0.001
+                if max >= maxs[i]: 
+                    maxs[i] = max + 0.001
+            
+        # Wrap atoms across periodic boundaries
+        spos -= imageflags
+        
+        # Unscale spos and save to pos
+        self.atoms_prop('pos', value=spos, scale=True)
+        
+        # Modify box vectors and origin by new min and max
+        origin = self.box.origin + mins.dot(self.box.vects) 
+        avect = self.box.avect * (maxs[0] - mins[0])
+        bvect = self.box.bvect * (maxs[1] - mins[1])
+        cvect = self.box.cvect * (maxs[2] - mins[2])
+        self.box_set(avect=avect, bvect=bvect, cvect=cvect, origin=origin)
+
+        if return_imageflags:
+            return imageflags
+    
+    def dvect(self,
+              pos_0: Union[int, list, slice, npt.ArrayLike],
+              pos_1: Union[int, list, slice, npt.ArrayLike]
+              ) -> np.ndarray:
+        """
+        Computes the shortest vector between pos_0 and pos_1 using box 
+        dimensions and accounting for periodic boundaries.
+        
+        Parameters
+        ----------
+        pos_0 : index or array-like object
+            Absolute Cartesian vector position(s) to use as reference point(s).
+            If the value can be used as an index, then self.atoms.pos[pos_0]
+            is taken.
+        pos_1 : index or array-like object
+            Absolute Cartesian vector position(s) to find relative to pos_0.
+            If the value can be used as an index, then self.atoms.pos[pos_1]
+            is taken.
+
+        Returns
+        -------
+        numpy.ndarray
+            The shortest vectors from each pos_0 to pos_1 positions.
+        """
+        # Test if pos_0 and pos_1 can be used as numpy array indices
+        try:
+            pos_0 = self.atoms.pos[pos_0]
+        except:
+            pos_0 = np.asarray(pos_0)
+        try:
+            pos_1 = self.atoms.pos[pos_1]
+        except:
+            pos_1 = np.asarray(pos_1)
+        
+        # Call dvect using self's box and pbc
+        vects = dvect(pos_0, pos_1, self.box, self.pbc)
+        if len(vects) == 1:
+            return vects[0]
+        else:
+            return vects
+
+    def dmag(self,
+             pos_0: Union[int, list, slice, npt.ArrayLike],
+             pos_1: Union[int, list, slice, npt.ArrayLike]
+             ) -> np.ndarray:
+        """
+        Computes the shortest distance between pos_0 and pos_1 using box 
+        dimensions and accounting for periodic boundaries.
+        
+        Parameters
+        ----------
+        pos_0 : index or array-like object
+            Absolute Cartesian vector position(s) to use as reference point(s).
+            If the value can be used as an index, then self.atoms.pos[pos_0]
+            is taken.
+        pos_1 : index or array-like object
+            Absolute Cartesian vector position(s) to find relative to pos_0.
+            If the value can be used as an index, then self.atoms.pos[pos_1]
+            is taken.
+        
+        Returns
+        -------
+        numpy.ndarray
+            The shortest vector magnitude from each pos_0 to pos_1 positions.
+        """
+        # Test if pos_0 and pos_1 can be used as numpy array indices
+        try:
+            pos_0 = self.atoms.pos[pos_0]
+        except:
+            pos_0 = np.asarray(pos_0)
+        try:
+            pos_1 = self.atoms.pos[pos_1]
+        except:
+            pos_1 = np.asarray(pos_1)
+        
+        # Call dvect using self's box and pbc
+        vects = dmag(pos_0, pos_1, self.box, self.pbc)
+        if len(vects) == 1:
+            return vects[0]
+        else:
+            return vects
+    
+    def neighborlist(self, **kwargs) -> NeighborList:
+        """
+        Builds a neighbor list for the system.  The resulting NeighborList
+        object is saved to the object as attribute 'neighbors'.
+        
+        Parameters
+        ----------
+        cutoff : float, optional
+            Radial cutoff distance for identifying neighbors.  Must be given if
+            model is not given.
+        model : str or file-like object, optional
+            Gives the file path or content to load.  If given, no other
+            parameters are allowed.
+        initialsize : int, optional
+            The number of neighbor positions to initially assign to each atom.
+            Default value is 20.
+        deltasize : int, optional
+            Specifies the number of extra neighbor positions to allow each atom
+            when the number of neighbors exceeds the underlying array size.
+            Default value is 10.
+            
+        Returns
+        -------
+        atomman.NeighborList
+            The compiled list of neighbors.
+        """
+        if 'system' in kwargs:
+            raise KeyError("Parameter 'system' not allowed")
+        else:
+            kwargs['system'] = self
+        return NeighborList(**kwargs)
+    
+    def r0(self,
+           neighbors: Optional[NeighborList] = None) -> float:
+        """
+        Identifies the shortest interatomic spacing between atoms in the
+        system by comparing the shortest periodic box vector with the
+        smallest dmags of all neighbor atoms.
+        
+        Parameters
+        ----------
+        neighbors : NeighborList, optional
+            A pre-computed NeighborList for the system.  If not given, a new
+            NeighborList will be computed using a cutoff distance based on the
+            smallest dmag between atom 0 and the rest of the system's atoms.
+        
+        Returns
+        -------
+        float
+            The shortest interatomic spacing identified.
+        """
+        
+        # Find shortest periodic lattice parameter
+        try:
+            box_r0 = np.linalg.norm(self.box.vects, axis=1)[self.pbc].min()
+        except:
+            box_r0 = None
+        
+        # Find shortest interatomic vector
+        if self.natoms > 1:
+            
+            # Compute neighbors if needed
+            if neighbors is None:
+                
+                # Use r0 for atom 0 as cutoff
+                cutoff = self.dmag(0, range(1, self.natoms)).min() * 1.01
+                
+                # Identify all neighbors
+                neighbors = self.neighborlist(cutoff=cutoff)
+            
+            # Find smallest r0 across all neighbor sets
+            atom_r0 = np.inf
+            for i in range(self.natoms):
+                j = neighbors[i]
+                if len(j) > 0:
+                    new_r0 = self.dmag(i, j).min()
+                    if new_r0 < atom_r0:
+                        atom_r0 = new_r0
+
+            if atom_r0 == np.inf:
+                atom_r0 = None
+        else:
+            atom_r0 = None
+
+        if box_r0 is not None and atom_r0 is not None:
+            if atom_r0 < box_r0:
+                return atom_r0
+            else:
+                return box_r0
+        elif box_r0 is not None:
+            return box_r0
+        elif atom_r0 is not None:
+            return atom_r0
+        else:
+            raise ValueError('No atoms to compare or periodic boundaries found!')
+    
+    def supersize(self,
+                  a_size: Union[int, Tuple[int, int]],
+                  b_size: Union[int, Tuple[int, int]],
+                  c_size: Union[int, Tuple[int, int]]) -> System:
+        """
+        Creates a larger system from a given system by replicating it along the
+        system's box vectors.
+        
+        The multiplier values \\*_size are taken to be integer tuples (m, n) where
+        m <= 0 and n >= 0.  The system multiplication works such that if n = -m,
+        then the seed system's origin will be at the center of the new system.
+        If only one integer is given, then it is assigned to m or n depending on
+        its sign, and the other value is taken to be 0.
+        
+        Parameters
+        ----------
+        a_size : int or tuple of int
+            Single int or two integers specifying replication along the avect
+            direction.
+        b_size -- int or tuple of int
+            Single int or two integers specifying replication along the bvect
+            direction.
+        c_size -- int or tuple of int
+            Single int or two integers specifying replication along the cvect
+            direction.
+        
+        Returns
+        -------
+        atomman.System
+            A new system created by replicating the given seed system according to
+            the \\*_size parameters.
+          
+        """
+        # Extract parameters
+        sizes = [a_size, b_size, c_size]
+        mults = np.array([0, 0, 0], dtype=int)
+        vects = self.box.vects
+        origin = self.box.origin
+        spos = self.atoms_prop('pos', scale=True)
+        
+        # Check the *_size values
+        for i in range(3):
+            
+            # Change single int to tuple of two int
+            if isinstance(sizes[i], (int, np.integer)):
+                if sizes[i] > 0:
+                    sizes[i] = (0, sizes[i])
+                elif sizes[i] < 0:
+                    sizes[i] = (sizes[i], 0)
+            
+            elif isinstance(sizes[i], tuple):
+                try:
+                    assert len(sizes[i]) == 2, str(len(sizes[i]))
+                    assert isinstance(sizes[i][0], (int, np.integer)), str(sizes[i][0])
+                    assert sizes[i][0] <= 0, str(sizes[i][0])
+                    assert isinstance(sizes[i][1], (int, np.integer)), str(sizes[i][1])
+                    assert sizes[i][1] >= 0, str(sizes[i][1])
+                except:
+                    raise TypeError('Invalid system multipliers')
+            else:
+                raise TypeError('Invalid system multipliers')
+            
+            # Calculate full multipliers 
+            mults[i] = sizes[i][1] - sizes[i][0]
+            if mults[i] == 0:
+                raise ValueError('Cannot multiply system dimension by zero')
+                
+            # Scale box and first set of positions accordingly
+            spos[:,i] /= mults[i]
+            origin += vects[i] * sizes[i][0]
+            vects[i] *= mults[i]
+            
+        # Initialize new Box and Atoms
+        box = Box(vects=vects, origin=origin)
+        natoms = self.natoms * mults[0] * mults[1] * mults[2]
+        atoms = Atoms(natoms=natoms)
+        
+        # Copy over all property values (except pos) using numpy broadcasting
+        for key in self.atoms_prop():
+            if key == 'pos':
+                continue
+        
+            # Get old array
+            old = self.atoms.view[key]
+            
+            # Create new array and broadcast old to it
+            new = np.empty((mults[0] * mults[1] * mults[2],) + old.shape, dtype = old.dtype)
+            new[:] = old
+            
+            # Reshape new and save to atoms
+            new_shape = new.shape
+            new_shape = (new_shape[0] * new_shape[1],) + new_shape[2:] # pylint: disable=unsubscriptable-object
+            atoms.view[key] = np.array(new.reshape(new_shape))
+        
+        # Expand spos using broadcasting
+        new_spos = np.empty((mults[0] * mults[1] * mults[2],) + spos.shape)
+        new_spos[:] = spos
+        
+        # Reshape spos
+        new_shape = new_spos.shape
+        new_shape = (new_shape[0]*new_shape[1],) + new_shape[2:] # pylint: disable=unsubscriptable-object
+        new_spos = new_spos.reshape(new_shape)
+        
+        # Use broadcasting to create arrays to add to spos
+        test = np.empty(mults[0] * self.natoms)
+        test.shape = (self.natoms, mults[0])
+        test[:] = np.arange(mults[0])
+        x = test.T.flatten()
+
+        test = np.empty(mults[1] * len(x))
+        test.shape = (len(x), mults[1])
+        test[:] = np.arange(mults[1])
+        y = test.T.flatten()
+        test.shape = (mults[1], len(x))
+        test[:] = x
+        x = test.flatten()
+
+        test = np.empty(mults[2] * len(x))
+        test.shape = (len(x), mults[2])
+        test[:] = np.arange(mults[2])
+        z = test.T.flatten()
+        test.shape = (mults[2], len(x))
+        test[:] = x
+        x = test.flatten()
+        test[:] = y
+        y = test.flatten()
+        
+        # xyz is displacement values to add to spos
+        xyz = (np.hstack((x[:, np.newaxis], y[:, np.newaxis], z[:, np.newaxis])) 
+             * np.array([1 / mults[0], 1 / mults[1], 1 / mults[2]]))
+        
+        # Save pos values, return new System
+        atoms.view['pos'] = new_spos + xyz
+        
+        return System(box=box, atoms=atoms, scale=True, symbols=self.symbols)
+    
+    def rotate(self,
+               uvws: npt.ArrayLike,
+               tol: Union[float, list, None] = None,
+               return_transform: bool = False) -> System:
+        """
+        Transforms a System representing a periodic crystal cell from a standard
+        orientation to a specified orientation. Note: if hexagonal indices are
+        given, the vectors will be reduced to the smallest uvw integer
+        representation.
+        
+        Parameters
+        ----------
+        uvws : array-like object
+            A (3, 3) array of the Miller crystal vectors or a (3, 4) array of
+            Miller-Bravais hexagonal crystal vectors to use in transforming the
+            system.  Values must be integers.
+        tol : list or float, optional
+            Tolerance parameter used in determining which atoms are inside the
+            box.  Multiple values can be given as the identification may
+            occasionally fail for a given ucell and tol.  Default behavior will
+            try tol values ranging from 1e-4 to 1e-8.
+        return_transform : bool, optional
+            Indicates if the transformation matrix associated with the
+            rotation is returned.  Default value is False.
+        
+        Returns
+        -------
+        atomman.System
+            A new fully periodic system rotated and transformed according to the
+            uvws crystal vectors.
+        transform : np.ndarray
+            The transformation matrix associated with the rotation.
+            Returned if return_transform is True.
+        """
+        
+        if tol is None:
+            tol = [1e-4, 1e-5, 1e-6, 1e-7]
+        else:
+            tol = aslist(tol)
+        
+        uvws = np.asarray(uvws)
+        
+        # Convert uvws from Miller-Bravais to Miller indices if needed
+        if uvws.shape == (3, 4):
+            if self.box.ishexagonal():
+                uvws = miller.vector4to3(uvws)
+            else:
+                raise ValueError('hexagonal indices only work on hexagonal systems')
+        
+        # Check uvws shape and values
+        if uvws.shape != (3, 3):
+            raise ValueError('Invalid uvws crystal indices shape')
+
+        int_uvws = np.asarray(np.rint(uvws), dtype='int64')
+        if np.allclose(uvws, int_uvws):
+            uvws = int_uvws
+        else:
+            raise ValueError('Rotation uvws must be integer values')
+        
+        # No rotation shortcut
+        if np.all(uvws == np.eye(3, dtype='int64')):
+            newsystem = deepcopy(self)
+        
+        else:
+            # Get natoms and volume of system
+            natoms = self.natoms
+            volume = self.box.volume
+            
+            # Convert uvws to Cartesian units and compute new volume and natoms
+            newvects = miller.vector_crystal_to_cartesian(uvws, box=self.box)
+            newvolume = np.abs(newvects[0].dot(np.cross(newvects[1], newvects[2])))
+            newnatoms = int(round(newvolume / volume) * natoms)
+            
+            # Check new values
+            if newnatoms == 0:
+                raise ValueError('New box has no atoms/volume: vectors are parallel or planar')
+            
+            # Identify box corners of new system wrt uvws
+            corners = np.empty((8,3), dtype='int64')
+            corners[0] = np.zeros(3)
+            corners[1] = uvws[0]
+            corners[2] = uvws[1]
+            corners[3] = uvws[2]
+            corners[4] = uvws[0] + uvws[1]
+            corners[5] = uvws[0] + uvws[2]
+            corners[6] = uvws[1] + uvws[2]
+            corners[7] = uvws[0] + uvws[1] + uvws[2]
+            
+            # Create a supercell of system that contains all box corners
+            a_mults = (corners[:,0].min()-1, corners[:,0].max()+1)
+            b_mults = (corners[:,1].min()-1, corners[:,1].max()+1)
+            c_mults = (corners[:,2].min()-1, corners[:,2].max()+1)
+            system2 = self.supersize(a_mults, b_mults, c_mults)
+            
+            # Change system.box.vects to newvects
+            system2.box_set(vects=newvects, scale=False)
+            
+            search_success = False
+            for atol in tol:
+                
+                spos = system2.atoms_prop('pos', scale=True)
+                
+                # Round atom positions near box boundaries to the boundaries
+                spos[np.isclose(spos, 0.0, atol=atol)] = 0.0
+                spos[np.isclose(spos, 1.0, atol=atol)] = 1.0
+            
+                # Identify all atoms whose positions are 0 <= x < 1
+                aindex = np.where(((spos[:, 0] >= 0.0) & (spos[:, 0] < 1.0)
+                                 & (spos[:, 1] >= 0.0) & (spos[:, 1] < 1.0)
+                                 & (spos[:, 2] >= 0.0) & (spos[:, 2] < 1.0)))
+                
+                # Check if number of atoms identified matches the expected number
+                if len(aindex[0]) == newnatoms:
+                    search_success = True
+                    break
+            
+            if not search_success:
+                raise ValueError(f'Filtering failed: {newnatoms} atoms expected, {len(aindex[0])} found')
+            
+            # Make newsystem by cutting out all atoms in system2 outside boundaries
+            newsystem = System(atoms=system2.atoms[aindex], box=system2.box, symbols=self.symbols)
+        
+        # Return normalized system
+        return newsystem.normalize(return_transform=return_transform)
+    
+    def normalize(self,
+                  style: str = 'lammps',
+                  return_transform: bool = False
+                  ) -> Union[System, Tuple[System, np.ndarray]]:
+        """
+        Normalizes a system's box vectors and atom positions to be compatible
+        with simulation codes.
+        
+        Parameters
+        ----------
+        style : str, optional
+            Indicates the normalization style to use.  Default (and only
+            current option) is 'lammps'.
+        return_transform : bool, optional
+            Indicates if the transformation matrix associated with the
+            normalization is returned.  Default value is False.
+        Returns
+        -------
+        newsystem : atomman.System
+            A new system that has been normalized.
+        transform : np.ndarray
+            The transformation matrix associated with the normalization.
+            Returned if return_transform is True.
+        """
+        if style == 'lammps':
+            return lmp_normalize(self, return_transform=return_transform)
+        else:
+            raise ValueError("Unknown style (only 'lammps' is currently supported)")
+    
+    def dump(self, style: str, **kwargs) -> Optional[Any]:
+        """
+        Convert a System to another format.
+    
+        Parameters
+        ----------
+        style : str
+            Indicates the format of the content to dump the atomman.System as.
+        kwargs
+            Any extra keyword arguments to pass to the underlying dump methods.
+            
+        Returns
+        -------
+        str, object or tuple
+            Any content returned by the underlying dump methods.
+        """
+        return dump(style, self, **kwargs)
+
+    def model(self,
+              box_unit: Optional[str] = None,
+              prop_name: Optional[list] = None,
+              unit: Optional[list] = None,
+              prop_unit: Optional[dict] = None) -> DM:
+        """
+        Generates a data model for the System object.
+
+        Parameters
+        ----------
+        box_unit : str, optional
+            Length unit to use for the box. Default value is 'angstrom'.
+        prop_name : list, optional
+            The Atoms properties to include.  If neither prop_name nor prop_unit
+            are given, all system properties will be included.
+        unit : list, optional
+            Lists the units for each prop_name as stored in the table.  For a
+            value of None, no conversion will be performed for that property.  For
+            a value of 'scaled', the corresponding table values will be taken in
+            box-scaled units.  If neither unit nor prop_units given, pos will be
+            given in Angstroms and all other values will not be converted.
+        prop_unit : dict, optional
+            dictionary where the keys are the property keys to include, and
+            the values are units to use. If neither unit nor prop_units given, 
+            pos will be given in Angstroms and all other values will not be
+            converted.
+
+        Returns
+        -------
+        DataModelDict.DataModelDict
+            A JSON/XML data model for the current System object. 
+        """
+
+        # Initialize DataModelDict
+        model = DM()
+        model['atomic-system'] = DM()
+
+        # Add box
+        model['atomic-system']['box'] = self.box.model(length_unit=box_unit)['box']
+        
+        # Add pbc
+        model['atomic-system']['periodic-boundary-condition'] = self.pbc.tolist()
+        
+        # Add symbols
+        for symbol in self.symbols:
+            model['atomic-system'].append('atom-type-symbol', symbol)
+
+        # Add masses
+        addmasses = False
+        for mass in self.masses:
+            if mass is not None:
+                addmasses = True
+                break
+        if addmasses:
+            for mass in self.masses:
+                model['atomic-system'].append('atom-type-mass', mass)
+        
+        # Add atoms
+        model['atomic-system']['atoms'] = amodel = self.atoms.model(prop_name=prop_name,
+                                                                    unit=unit, 
+                                                                    prop_unit=prop_unit)['atoms']
+        
+        # Scale properties if needed
+        for prop in amodel.aslist('property'):
+            if prop['data'].get('unit', None) == 'scaled':
+                prop['data'] = uc.model(self.box.position_cartesian_to_relative(uc.value_unit(prop['data'])), units='scaled') 
+        
+        return model

atomman/source/atomman/core/__init__.py

@@ -0,0 +1,14 @@
+# coding: utf-8
+from .dvect import dvect
+from .dmag import dmag 
+from .nlist import nlist 
+from .NeighborList import NeighborList
+from .Atoms import Atoms
+from .Box import Box
+from .ElasticConstants import ElasticConstants
+from .ElasticConstants2 import ElasticConstants2
+from .System import System
+from .displacement import displacement
+
+__all__ = ['displacement', 'dvect', 'dmag', 'nlist', 'Atoms', 'Box',
+           'ElasticConstants', 'ElasticConstants2', 'NeighborList', 'System']

atomman/source/atomman/core/displacement.py

@@ -0,0 +1,49 @@
+# coding: utf-8
+
+# http://www.numpy.org/
+import numpy as np
+
+# atomman imports
+from . import dvect
+
+def displacement(system_0, system_1, box_reference: str = 'final') -> np.ndarray:
+    """
+    Compute the displacement vectors between all matching atoms for two systems.
+    
+    Parameters
+    ----------
+    system_0 : atomman.System
+        The initial system to calculate displacements from.
+    system_1 : atomman.System
+        The final system to calculate displacements to.
+    box_reference : str or None
+        Specifies which system's boundary conditions to use.  'initial' uses
+        system_0's box and pbc.  'final' uses system_1's box and pbc (Default)
+        None computes the straight difference between the positions without
+        accounting for periodic boundaries.
+    
+    Returns
+    -------
+    numpy.ndarray
+        The displacement vectors for all atoms.
+        
+    Raises
+    ------
+    ValueError
+        If the systems have different numbers of atoms or for invalid
+        box_reference values.
+    """
+    if system_0.natoms != system_1.natoms:
+        raise ValueError('systems have different number of atoms')
+    
+    if box_reference == 'final':
+        disp = dvect(system_0.atoms.pos, system_1.atoms.pos, system_1.box, system_1.pbc)
+    elif box_reference == 'initial':
+        disp = dvect(system_0.atoms.pos, system_1.atoms.pos, system_0.box, system_0.pbc)
+    elif box_reference is None:
+        disp = system_1.atoms.pos - system_0.atoms.pos
+    else:
+        raise ValueError("box_reference must be 'final', 'initial', or None")
+    
+    return disp
+    

atomman/source/atomman/core/dmag.pxd

@@ -0,0 +1,3 @@
+# coding: utf-8
+# cython: language_level=3
+cdef dmag2_c(const double[:,:], const double[:,:], const double[:,:], const bint, const bint, const bint)

atomman/source/atomman/core/dmag.pyx

@@ -0,0 +1,150 @@
+# coding: utf-8
+# cython: language_level=3
+# Standard Python libraries
+from copy import deepcopy
+
+# http://cython.org/
+import cython
+
+# http://www.numpy.org/
+import numpy as np
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def dmag(pos_0, pos_1, box, pbc):
+    """
+    Computes the shortest distance between pos_0 and pos_1 using box
+    dimensions and accounting for periodic boundaries.
+
+    Parameters
+    ----------
+    pos_0 : numpy.ndarray, list, or tuple
+        Absolute Cartesian vector position(s) to use as reference point(s).
+    pos_1 : numpy.ndarray, list, or tuple
+        Absolute Cartesian vector position(s) to find relative to pos_0.
+    box : atomman.Box
+        Defines the system/box dimensions
+    pbc : list, tuple, or numpy.ndarray of bool.
+        Three Boolean values indicating which of the three box vectors are
+        periodic (True means periodic).
+
+    Returns
+    -------
+    numpy.ndarray
+        The shortest vector magnitude from each pos_0 to pos_1 positions.
+    """
+    
+    # Convert pos_0 to numpy array with proper dimensions
+    pos_0 = np.asarray(pos_0, dtype=np.float64)
+    if pos_0.ndim == 0:
+        raise TypeError('Invalid pos_0')
+    if pos_0.ndim == 1:
+        pos_0 = pos_0[np.newaxis, :]
+
+    # Convert pos_1 to numpy array with proper dimensions
+    pos_1 = np.asarray(pos_1, dtype=np.float64)
+    if pos_1.ndim == 0:
+        raise TypeError('Invalid pos_1')
+    if pos_1.ndim == 1:
+        pos_1 = pos_1[np.newaxis, :]
+
+    # Broadcast to compatible lengths
+    if len(pos_0) == 1:
+        pos_0 = np.broadcast_to(pos_0, pos_1.shape)
+    elif len(pos_1) == 1:
+        pos_1 = np.broadcast_to(pos_1, pos_0.shape)
+    elif len(pos_0) != len(pos_1):
+        raise ValueError('Incompatible pos lengths')
+
+    # Extract box vectors
+    bvects = box.vects
+
+    # Call the cython function
+    return dmag2_c(pos_0, pos_1, bvects, pbc[0], pbc[1], pbc[2])**0.5
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+cdef dmag2_c(const double[:,:] pos_0,
+             const double[:,:] pos_1, 
+             const double[:,:] bvects,
+             const bint pbc_x,
+             const bint pbc_y,
+             const bint pbc_z):
+    """
+    Computes the shortest distance between pos_0 and pos_1 using box 
+    dimensions and accounting for periodic boundaries.
+    
+    Parameters
+    ----------
+    pos_0 : cython.memoryview
+        Absolute Cartesian vector position(s) to use as reference point(s).
+    pos_1 : cython.memoryview
+        Absolute Cartesian vector position(s) to find relative to pos_0.
+    bvects : cython.memoryview
+        3x3 array defining the system/box dimensions.
+    pbc_x : bint
+        Flag indicating to make x periodic.
+    pbc_y : bint
+        Flag indicating to make y periodic.
+    pbc_z : bint
+        Flag indicating to make z periodic.
+
+    Returns
+    -------
+    cython.memoryview
+        The shortest vector magnitude squared from each pos_0 to pos_1 positions.
+    """
+    
+    # Define parameters
+    cdef Py_ssize_t ni = pos_0.shape[0]
+    cdef Py_ssize_t nj = 3
+    cdef Py_ssize_t i, j, x, y, z, xl, xh, yl, yh, zl, zh
+    cdef double mag2_test
+    cdef double[:] d = np.empty(3, dtype=np.float64)
+    
+    # Define output array and its view
+    mag2_d = np.empty(ni, dtype=np.float64)
+    cdef double [:] mag2_dv = mag2_d
+
+    # Create iterators based on pbc
+    if pbc_x:
+        xl, xh = -1, 2
+    else:
+        xl, xh = 0, 1
+    if pbc_y:
+        yl, yh = -1, 2
+    else:
+        yl, yh = 0, 1
+    if pbc_z:
+        zl, zh = -1, 2
+    else:
+        zl, zh = 0, 1
+    
+    # Loop over all pos
+    for i in range(ni):
+       
+        # Compute pos_1 - pos_0 
+        for j in range(nj):
+            d[j] = pos_1[i,j] - pos_0[i,j]
+        mag2_dv[i] = d[0] * d[0] + d[1] * d[1] + d[2] * d[2]
+        
+        # Loop over all periodic boundary conditions
+        for x in range(xl, xh):
+            for y in range(yl, yh):
+                for z in range(zl, zh):
+                    if x == 0 and y == 0 and z == 0:
+                        continue
+                    
+                    # Compute pos_1 - pos_0 + boundary image shifts
+                    for j in range(nj):
+                        d[j] = (pos_1[i,j] - pos_0[i,j] 
+                                + x * bvects[0,j] 
+                                + y * bvects[1,j] 
+                                + z * bvects[2,j])
+                    
+                    # Replace d if new vector is smaller
+                    mag2_test = d[0] * d[0] + d[1] * d[1] + d[2] * d[2]
+                    if mag2_test < mag2_dv[i]:
+                        mag2_dv[i] = mag2_test
+
+    return mag2_d 

atomman/source/atomman/core/dvect.pxd

@@ -0,0 +1,3 @@
+# coding: utf-8
+# cython: language_level=3
+cdef dvect_c(const double[:,:], const double[:,:], const double[:,:], const bint, const bint, const bint)

atomman/source/atomman/core/dvect.pyx

@@ -0,0 +1,153 @@
+# coding: utf-8
+# cython: language_level=3
+# Standard Python libraries
+from __future__ import (absolute_import, print_function,
+                        division, unicode_literals)
+from copy import deepcopy
+
+# http://cython.org/
+import cython
+
+# http://www.numpy.org/
+import numpy as np
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def dvect(pos_0, pos_1, box, pbc):
+    """
+    Computes the shortest vector between pos_0 and pos_1 using box
+    dimensions and accounting for periodic boundaries.
+
+    Parameters
+    ----------
+    pos_0 : numpy.ndarray, list, or tuple
+        Absolute Cartesian vector position(s) to use as reference point(s).
+    pos_1 : numpy.ndarray, list, or tuple
+        Absolute Cartesian vector position(s) to find relative to pos_0.
+    box : atomman.Box
+        Defines the system/box dimensions
+    pbc : list, tuple, or numpy.ndarray of bool.
+        Three Boolean values indicating which of the three box vectors are
+        periodic (True means periodic).
+
+    Returns
+    -------
+    numpy.ndarray
+        The shortest vectors from each pos_0 to pos_1 positions.
+    """
+    
+    # Convert pos_0 to numpy array with proper dimensions
+    pos_0 = np.asarray(pos_0, dtype=np.float64)
+    if pos_0.ndim == 0:
+        raise TypeError('Invalid pos_0')
+    if pos_0.ndim == 1:
+        pos_0 = pos_0[np.newaxis, :]
+
+    # Convert pos_1 to numpy array with proper dimensions
+    pos_1 = np.asarray(pos_1, dtype=np.float64)
+    if pos_1.ndim == 0:
+        raise TypeError('Invalid pos_1')
+    if pos_1.ndim == 1:
+        pos_1 = pos_1[np.newaxis, :]
+
+    # Broadcast to compatible lengths
+    if len(pos_0) == 1:
+        pos_0 = np.broadcast_to(pos_0, pos_1.shape)
+    elif len(pos_1) == 1:
+        pos_1 = np.broadcast_to(pos_1, pos_0.shape)
+    elif len(pos_0) != len(pos_1):
+        raise ValueError('Incompatible pos lengths')
+
+    # Extract box vectors
+    bvects = box.vects
+
+    # Call the cython function
+    return dvect_c(pos_0, pos_1, bvects, pbc[0], pbc[1], pbc[2])
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+cdef dvect_c(const double[:,:] pos_0,
+             const double[:,:] pos_1, 
+             const double[:,:] bvects,
+             const bint pbc_x,
+             const bint pbc_y,
+             const bint pbc_z):
+    """
+    Computes the shortest distance between pos_0 and pos_1 using box 
+    dimensions and accounting for periodic boundaries.
+    
+    Parameters
+    ----------
+    pos_0 : cython.memoryview
+        Absolute Cartesian vector position(s) to use as reference point(s).
+    pos_1 : cython.memoryview
+        Absolute Cartesian vector position(s) to find relative to pos_0.
+    bvects : cython.memoryview
+        3x3 array defining the system/box dimensions.
+    pbc_x : bint
+        Flag indicating to make x periodic.
+    pbc_y : bint
+        Flag indicating to make y periodic.
+    pbc_z : bint
+        Flag indicating to make z periodic.
+
+    Returns
+    -------
+    cython.memoryview
+        The shortest vectors from each pos_0 to pos_1 positions.
+    """
+    
+    # Define parameters
+    cdef Py_ssize_t ni = pos_0.shape[0]
+    cdef int nj = 3
+    cdef int i, j, x, y, z, xl, xh, yl, yh, zl, zh    
+    cdef double[:] test = np.empty(3)
+    cdef double mag_test, mag_d
+    
+    # Define output array and its view
+    d = np.empty_like(pos_0, np.float64)
+    cdef double[:,:] dv = d
+    
+    # Create iterators based on pbc
+    if pbc_x:
+        xl, xh = -1, 2
+    else:
+        xl, xh = 0, 1
+    if pbc_y:
+        yl, yh = -1, 2
+    else:
+        yl, yh = 0, 1
+    if pbc_z:
+        zl, zh = -1, 2
+    else:
+        zl, zh = 0, 1
+    
+    # Loop over all pos
+    for i in range(ni):
+       
+        # Compute pos_1 - pos_0 
+        for j in range(nj):
+            dv[i,j] = pos_1[i,j] - pos_0[i,j]
+        
+        # Loop over all periodic boundary conditions
+        for x in range(xl, xh):
+            for y in range(yl, yh):
+                for z in range(zl, zh):
+                    if x == 0 and y == 0 and z == 0:
+                        continue
+                    
+                    # Compute pos_1 - pos_0 + boundary image shifts
+                    for j in range(nj):
+                        test[j] = (pos_1[i,j] - pos_0[i,j] 
+                                   + x * bvects[0,j] 
+                                   + y * bvects[1,j] 
+                                   + z * bvects[2,j])
+                    
+                    # Replace d if new vector is smaller
+                    mag_test = test[0] * test[0] + test[1] * test[1] + test[2] * test[2]
+                    mag_d = dv[i,0] * dv[i,0] + dv[i,1] * dv[i,1] + dv[i,2] * dv[i,2]
+                    if mag_test < mag_d:
+                        for j in range(nj):
+                            dv[i,j] = test[j]
+
+    return d

atomman/source/atomman/core/nlist.pyx

@@ -0,0 +1,334 @@
+# coding: utf-8
+# cython: language_level=3
+
+# http://cython.org/
+import cython
+
+# http://www.numpy.org/
+import numpy as np
+
+# atomman imports
+from .dmag cimport dmag2_c   
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def nlist(system, double cutoff, Py_ssize_t initialsize=20, Py_ssize_t deltasize=10):
+    """
+    Calculates a neighbor list for all atoms in a System taking periodic
+    boundaries into account.
+    
+    Parameters
+    ----------
+    system : atomman.System 
+        The system to calculate the neighbor list for.
+    cutoff : float
+        Radial cutoff distance for identifying neighbors.
+    initialsize : int, optional
+        The number of neighbor positions to initially assign to each atom.
+        Default value is 20.
+    deltasize : int, optional
+        Specifies the number of extra neighbor positions to allow each atom
+        when the number of neighbors exceeds the underlying array size.
+        Default value is 10.
+
+    Returns
+    -------
+    numpy.ndarray of int
+        Array listing number of neighbors and neighbor ids for each atom in
+        System.  First term in each row is the atom's coordination number, c.
+        The next c values are the atom's neighbor ids.  
+    """
+    
+    # Define variables based on input parameters
+    pos = system.atoms.pos
+    cdef const double[:,:] posv = pos
+    cdef const double[:,:] vects = system.box.vects
+    cdef const double[:] origin = system.box.origin
+    cdef bint pbc_a = system.pbc[0]
+    cdef bint pbc_b = system.pbc[1]
+    cdef bint pbc_c = system.pbc[2]
+    cdef Py_ssize_t maxneighbors = initialsize
+    cdef Py_ssize_t maxatomsperbin = 40
+    cdef Py_ssize_t natoms = posv.shape[0]
+    cdef double cutoff2 = cutoff*cutoff
+   
+    # Define basic iteration index variables
+    cdef Py_ssize_t i, j, k, l
+
+    # Define superbox identification parameters
+    cdef Py_ssize_t x, y, z
+    cdef double corner
+    cdef double[:] supermin=np.empty(3)
+    cdef double[:] supermax=np.empty(3)
+    
+    # Define bins
+    cdef double binsize
+    cdef double[:] xbins, ybins, zbins
+    cdef Py_ssize_t numxbins, numybins, numzbins
+    
+    # Define bin indexers and associated atom indexes
+    #cdef long long [:] xindex, yindex, zindex
+    #cdef long long [:,:] xyzindex
+    cdef long long [:] atomindex
+    cdef long long [:,:] newxyzindex
+    cdef long long [:] newatomindex
+    
+    # Define ghost atom info
+    cdef Py_ssize_t xl, xh, yl, yh, zl, zh
+    cdef double[:,:] ghostpos = np.empty((0, 3))
+    cdef double[:,:] newghostpos
+    newpos = np.empty(pos.shape)
+    cdef double[:,:] newposv = newpos
+    cdef long long[:] ghostindex = np.empty(0, dtype=np.int64)
+    cdef long long[:] newindex = np.empty(posv.shape[0], dtype=np.int64)
+    cdef long long[:] newghostindex 
+    cdef long long [:,:] xyzghostindex
+    
+    # Define final bins
+    cdef Py_ssize_t maxc, c, n
+    cdef Py_ssize_t dc, dx, dy, dz
+    cdef long long[:, :, :, :] xyzbins, newbins
+    
+    # Define lists of atoms to compare
+    cdef Py_ssize_t uindex, vindex, u, v, w
+    cdef long long [:] shortlist, longlist, superlonglist
+    cdef bint end
+    
+    # Define positions and distances between them
+    cdef double[:,:] upos, vpos
+    cdef double[:] dmag2
+    
+    # Define neighbors list and assignment terms
+    cdef Py_ssize_t uj, vj
+    cdef long long[:, :] neighbors = np.empty((natoms, maxneighbors+1), dtype=np.int64)
+    for i in range(natoms):
+        neighbors[i, 0] = 0
+    cdef long long[:, :] newneighbors
+    cdef bint isnew
+
+    # Determine orthogonal superbox that fully encompasses the system
+    for j in range(3):
+        supermin[j] = origin[j]
+        supermax[j] = origin[j]
+    for z in range(0, 2):
+        for y in range(0, 2):
+            for x in range(0, 2):
+                for j in range(3):
+                    corner = origin[j] + x * vects[0, j] + y * vects[1, j] + z * vects[2, j]
+                    if corner < supermin[j]:
+                        supermin[j] = corner
+                    if corner > supermax[j]:
+                        supermax[j] = corner
+    for j in range(3):
+        supermin[j] -= 1.01 * cutoff
+        supermax[j] += 1.01 * cutoff
+    
+    # Construct bins
+    binsize = cutoff
+    xbins = np.arange(supermin[0], supermax[0] + binsize, binsize)
+    ybins = np.arange(supermin[1], supermax[1] + binsize, binsize)
+    zbins = np.arange(supermin[2], supermax[2] + binsize, binsize)
+    numxbins = len(xbins)
+    numybins = len(ybins)
+    numzbins = len(zbins)
+    
+    # Build xyz box index for each atom
+    xindex = np.digitize(pos[:, 0], xbins) - 1
+    yindex = np.digitize(pos[:, 1], ybins) - 1
+    zindex = np.digitize(pos[:, 2], zbins) - 1
+    xyzindex = np.hstack((xindex[:, np.newaxis], yindex[:, np.newaxis], zindex[:, np.newaxis]))
+    
+    # Relate atom's id to xyz_index
+    atomindex = np.arange(natoms, dtype=np.int64)
+    
+    # Identify all bins with real atoms
+    realbins = unique_rows2(xyzindex)
+    
+    # Create iterators based on pbc
+    if pbc_a:
+        xl, xh = -1, 2
+    else:
+        xl, xh = 0, 1
+    if pbc_b:
+        yl, yh = -1, 2
+    else:
+        yl, yh = 0, 1
+    if pbc_c:
+        zl, zh = -1, 2
+    else:
+        zl, zh = 0, 1
+
+    # Construct list of ghost atoms in the superbox
+    for x in range(xl, xh):
+        for y in range(yl, yh):
+            for z in range(zl, zh):
+                if x == 0 and y == 0 and z == 0:
+                    pass
+                else:
+                    k=0
+                    for i in range(posv.shape[0]):
+                        for j in range(3):
+                            newposv[i, j] = x * vects[0, j] + y * vects[1, j] + z * vects[2, j] + posv[i, j]
+
+                        if (    newposv[i, 0] > supermin[0] and newposv[i, 0] < supermax[0]
+                            and newposv[i, 1] > supermin[1] and newposv[i, 1] < supermax[1]
+                            and newposv[i, 2] > supermin[2] and newposv[i, 2] < supermax[2]):
+                            
+                            newindex[k] = i
+                            k += 1
+
+                    ghostpos = np.vstack((ghostpos, newpos[newindex[:k]]))
+                    ghostindex = np.hstack((ghostindex, newindex[:k]))
+
+    # Append xyzindex and atomindex lists with ghost atoms
+    if len(ghostpos) > 0:
+        xindex = np.digitize(ghostpos[:, 0], xbins) - 1
+        yindex = np.digitize(ghostpos[:, 1], ybins) - 1
+        zindex = np.digitize(ghostpos[:, 2], zbins) - 1
+        xyzghostindex = np.hstack((xindex[:, np.newaxis], 
+                                   yindex[:, np.newaxis],
+                                   zindex[:, np.newaxis]))
+        xyzindex = np.vstack((xyzindex, xyzghostindex))
+        atomindex = np.hstack((atomindex, ghostindex))
+    
+    # Assign atoms and ghost atoms to xyz bins
+    maxc = 0
+    xyzbins = np.zeros((numxbins, numybins, numzbins, maxatomsperbin + 1), dtype=np.int64)
+    for n in range(atomindex.shape[0]):
+        x, y, z = xyzindex[n]
+        c = xyzbins[x, y, z, 0] + 1
+        
+        # Increase size if needed
+        if c == maxatomsperbin:
+            newbins = np.zeros((numxbins, numybins, numzbins, maxatomsperbin + 11), dtype=np.int64)
+            for i in range(xyzbins.shape[0]):
+                for j in range(xyzbins.shape[1]):
+                    for k in range(xyzbins.shape[2]):
+                        for l in range(maxatomsperbin + 1):
+                            newbins[i, j, k, l] = xyzbins[i, j, k, l]
+            xyzbins = newbins
+            maxatomsperbin += 10
+        
+        if c > maxc:
+            maxc = c
+        xyzbins[x, y, z, 0] = c
+        xyzbins[x, y, z, c] = atomindex[n]
+
+    superlonglist = np.empty(14 * maxc, dtype=np.int64)
+
+    # Iterate over all bins with real atoms
+    for i in range(len(realbins)):
+        x, y, z = realbins[i]
+        c = xyzbins[x, y, z, 0]
+        shortlist = np.empty(c, dtype=np.int64)
+        
+        # shortlist = all atoms in current bin
+        for j in range(c):
+            shortlist[j] = xyzbins[x, y, z, j+1]
+            superlonglist[j] = shortlist[j]
+        
+        # Add all atoms in half of the nearby bins to longlist
+        end = False
+        for dz in range(-1, 2):
+            for dy in range(-1, 2):
+                for dx in range(-1, 2):
+                    
+                    # Stop when reach center bin
+                    if dx == 0 and dy == 0 and dz == 0:
+                        end = True
+                        break
+                    
+                    # Skip non-existant neighbor bins
+                    if (x + dx < 0 or x + dx == numxbins or
+                        y + dy < 0 or y + dy == numybins or
+                        z + dz < 0 or z + dz == numzbins):
+                        continue
+                    
+                    dc = xyzbins[x + dx, y + dy, z + dz, 0]
+                    for j in range(dc):
+                        superlonglist[c+j] = xyzbins[x + dx, y + dy, z + dz, j+1]
+                    c += dc
+                if end:
+                    break
+            if end:
+                break
+                
+        longlist = superlonglist[:c]
+        
+        # Compare all atoms in shortlist to longlist.
+        for u in range(shortlist.shape[0]):
+            uindex = shortlist[u]
+            
+            upos = np.empty((longlist.shape[0]-u-1, 3))
+            vpos = np.empty((longlist.shape[0]-u-1, 3))
+
+            for w, v in enumerate(range(u+1, longlist.shape[0])):
+                for j in range(3):
+                    vindex = longlist[v]
+                    upos[w, j] = posv[uindex, j]
+                    vpos[w, j] = posv[vindex, j]
+            
+            # Compute distances
+            dmag2 = dmag2_c(upos, vpos, vects, pbc_a, pbc_b, pbc_c)
+            
+            # Assign neighbors if within cutoff
+            for w, v in enumerate(range(u+1, longlist.shape[0])):
+                if dmag2[w] < cutoff2:
+                    vindex = longlist[v]
+            
+                    if uindex != vindex:
+                        isnew = True
+                        uj = -1
+                        vj = -1
+                        
+                        # Find uj position to insert vindex
+                        for j in range(1, neighbors[uindex, 0] + 1):
+                            # Check uindex's neighbors for vindex
+                            if neighbors[uindex, j] == vindex:
+                                isnew = False
+                                break
+                            elif neighbors[uindex, j] > vindex:
+                                uj = j
+                                break
+                        if uj == -1:
+                            uj = neighbors[uindex, 0] + 1
+
+                        if isnew:
+                            # Find vj position to insert uindex
+                            for j in range(1, neighbors[vindex, 0] + 1):
+                                if neighbors[vindex, j] > uindex:
+                                    vj = j
+                                    break
+                            if vj == -1:
+                                vj = neighbors[vindex, 0] + 1
+
+                            # Increase coordination
+                            neighbors[uindex, 0] += 1
+                            neighbors[vindex, 0] += 1
+
+                            # Extend system size if needed
+                            if neighbors[uindex, 0] > maxneighbors or neighbors[vindex, 0] > maxneighbors:
+                                newneighbors = np.empty((natoms, maxneighbors + deltasize + 1), dtype=np.int64)
+                                for j in range(neighbors.shape[0]):
+                                    for k in range(maxneighbors + 1):
+                                        newneighbors[j, k] = neighbors[j, k]
+                                neighbors = newneighbors
+                                maxneighbors += deltasize
+
+                            # Shift neighbor indices with higher values
+                            for j in range(neighbors[uindex, 0], uj - 1, -1):
+                                neighbors[uindex, j] = neighbors[uindex, j - 1]
+                            for j in range(neighbors[vindex, 0], vj - 1, -1):
+                                neighbors[vindex, j] = neighbors[vindex, j - 1]
+
+                            # Assign neighbors to each other
+                            neighbors[uindex, uj] = vindex
+                            neighbors[vindex, vj] = uindex
+
+    return np.asarray(neighbors)
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def unique_rows2(a):  
+    """Takes two-dimensional array a and returns only the unique rows."""
+    return np.unique(a.view(np.dtype((np.void, a.dtype.itemsize*a.shape[1])))).view(a.dtype).reshape(-1, a.shape[1])

atomman/source/atomman/defect/Boundary.py

@@ -0,0 +1,803 @@
+# coding: utf-8
+# Standard Python imports
+from typing import Optional, Tuple
+from math import ceil
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+from scipy.spatial.transform import Rotation
+
+# Local imports
+from .. import System
+from ..tools import vect_angle, iaslist, miller
+
+
+class Boundary():
+    """
+    Class for generating systems to investigate grain/phase boundaries
+    """
+    def __init__(self,
+                 ucell1: System,
+                 ucell2: System,
+                 uvws1: npt.ArrayLike,
+                 uvws2: npt.ArrayLike,
+                 conventional_setting1: str = 'p',
+                 conventional_setting2: str = 'p',
+                 cutboxvector: str = 'c',
+                 zerostrain: bool = False,
+                 maxmult: int = 10,
+                 tol: float = 1e-8):
+        """
+        Class initializer.  This is generic to allow for either a grain or
+        phase boundary to be specified.
+
+        Parameters
+        ----------
+        ucell1 : atomman.System
+            The reference unit cell to use for the first grain.
+        ucell2 : atomman.System
+            The reference unit cell to use for the second grain.
+        uvws1 : array-like object
+            The three Miller(-Bravais) crystal vectors of ucell1 to use for
+            orienting the first grain such that each crystal vector will be
+            aligned with one of the box vectors of the final configuration.
+        uvws2 : array-like object
+            The three Miller(-Bravais) crystal vectors of ucell2 to use for
+            orienting the second grain such that each crystal vector will be
+            aligned with one of the box vectors of the final configuration.
+        conventional_setting1 : str, optional
+            Specifies which conventional lattice setting that ucell1 is in.
+            The default value of 'p' takes ucell to be primitive, in which case
+            the uvws1 values must be integers.  This must be specified
+            in order to access non-integer lattice vectors for uvws1. 
+        conventional_setting2 : str, optional
+            Specifies which conventional lattice setting that ucell1 is in.
+            The default value of 'p' takes ucell to be primitive, in which case
+            the uvws1 values must be integers.  This must be specified
+            in order to access non-integer lattice vectors for uvws1. 
+        cutboxvector : str, optional
+            Indicates which of the three box vectors that the boundary will
+            be placed along. Default value is 'c'.
+        zerostrain : bool, optional
+            Setting this as True will check to see if the orientations of the
+            two grains are fully compatible without introducing strain.  This
+            is important for grain boundary energy comparisons.  Default value
+            is False (no check performed).
+        maxmult : int, optional
+            The max integer multiplier to use for the zero strain check if
+            zerostrain is True. 
+        """
+        # Set default values
+        self.__mults1 = np.zeros(3)
+        self.__mults2 = np.zeros(3)
+
+        # Save given settings
+        self.__ucell1 = ucell1
+        self.__ucell2 = ucell2
+        self.__uvws1 = uvws1
+        self.__uvws2 = uvws2
+        self.__cutboxvector = cutboxvector
+
+        # Generate compatible primitive unit cells and associated transformation matrixes
+        ucell_prim1, transform_c1_to_p1 = ucell1.dump('conventional_to_primitive',
+                                                     setting=conventional_setting1,
+                                                     return_transform=True, atol=tol)
+        ucell_prim2, transform_c2_to_p2 = ucell2.dump('conventional_to_primitive',
+                                                      setting=conventional_setting2,
+                                                      return_transform=True, atol=tol)
+
+        # Handle uvws inputs
+        uvws1, uvws_prim1 = interpret_rotation_uvws(uvws1, conventional_setting=conventional_setting1)
+        uvws2, uvws_prim2 = interpret_rotation_uvws(uvws2, conventional_setting=conventional_setting2)
+
+        # Save primitive cell settings
+        self.__ucell_prim1 = ucell_prim1
+        self.__ucell_prim2 = ucell_prim2
+        self.__transform_c1_to_p1 = Rotation.from_matrix(transform_c1_to_p1)
+        self.__transform_c2_to_p2 = Rotation.from_matrix(transform_c2_to_p2)
+        self.__uvws_prim1 = uvws_prim1
+        self.__uvws_prim2 = uvws_prim2
+
+        # Create rotated cells
+        rcell1, transform_p1_to_r1 = ucell_prim1.rotate(uvws_prim1, return_transform=True)
+        rcell2, transform_p2_to_r2 = ucell_prim2.rotate(uvws_prim2, return_transform=True)
+        clean_wrap(rcell1)
+        clean_wrap(rcell1)
+        self.__rcell1 = rcell1
+        self.__rcell2 = rcell2
+        self.__transform_p1_to_r1 = Rotation.from_matrix(transform_p1_to_r1)
+        self.__transform_p2_to_r2 = Rotation.from_matrix(transform_p2_to_r2)
+
+        # Check boxvectors
+        if cutboxvector == 'a':
+            if rcell1.box.bvect[0] != 0.0 or rcell1.box.cvect[0] != 0.0:
+                raise ValueError("box bvect and cvect cannot have x component for cutboxvector='a'")
+            if rcell2.box.bvect[0] != 0.0 or rcell2.box.cvect[0] != 0.0:
+                raise ValueError("box bvect and cvect cannot have x component for cutboxvector='a'")
+            self.__cutindex = 0
+
+        elif cutboxvector == 'b':
+            if rcell1.box.avect[1] != 0.0 or rcell1.box.cvect[1] != 0.0:
+                raise ValueError("box avect and cvect cannot have y component for cutboxvector='b'")
+            if rcell2.box.avect[1] != 0.0 or rcell2.box.cvect[1] != 0.0:
+                raise ValueError("box avect and cvect cannot have y component for cutboxvector='b'")
+            self.__cutindex = 1
+
+        elif cutboxvector == 'c':
+            if rcell1.box.avect[2] != 0.0 or rcell1.box.bvect[2] != 0.0:
+                raise ValueError("box avect and bvect cannot have z component for cutboxvector='c'")
+            if rcell2.box.avect[2] != 0.0 or rcell2.box.bvect[2] != 0.0:
+                raise ValueError("box avect and bvect cannot have z component for cutboxvector='c'")
+            self.__cutindex = 2
+
+        for i in range(3):
+            if i == self.cutindex:
+                continue
+            if not np.isclose(vect_angle(rcell1.box.vects[i], rcell2.box.vects[i]), 0.0):
+                raise ValueError('in-plane vectors of the two grains must be parallel')
+
+        if zerostrain:
+            strain = self.identifymults(maxmult)[2]
+            if not np.allclose(strain, np.zeros(3)):
+                raise ValueError('no zero strain configuration found') 
+
+    @property
+    def uvws1(self) -> np.ndarray:
+        """numpy.NDArray: The three crystal vectors used to orient the first grain expressed as Miller(-Bravais) vectors of ucell1"""
+        return self.__uvws1
+
+    @property
+    def uvws2(self) -> np.ndarray:
+        """numpy.NDArray: The three crystal vectors used to orient the second grain expressed as Miller(-Bravais) vectors of ucell2"""
+        return self.__uvws2
+
+    @property
+    def uvws_prim1(self) -> np.ndarray:
+        """numpy.NDArray: The three crystal vectors used to orient the first grain expressed as Miller vectors of ucell_prim1"""
+        return self.__uvws_prim1
+
+    @property
+    def uvws_prim2(self) -> np.ndarray:
+        """numpy.NDArray: The three crystal vectors used to orient the second grain expressed as Miller vectors of ucell_prim2"""
+        return self.__uvws_prim2
+
+    @property
+    def ucell1(self) -> System:
+        """atomman.System: The conventional reference unit cell for the first grain."""
+        return self.__ucell1
+
+    @property
+    def ucell2(self) -> System:
+        """atomman.System: The conventional reference unit cell for the second grain."""
+        return self.__ucell2
+    
+    @property
+    def ucell_prim1(self) -> System:
+        """atomman.System: The primitive reference unit cell for the first grain."""
+        return self.__ucell_prim1
+
+    @property
+    def ucell_prim2(self) -> System:
+        """atomman.System: The primitive reference unit cell for the second grain."""
+        return self.__ucell_prim2
+
+    @property
+    def rcell1(self) -> System:
+        """atomman.System: The rotated cell for the first grain."""
+        return self.__rcell1
+
+    @property
+    def rcell2(self) -> System:
+        """atomman.System: The rotated cell for the second grain."""
+        return self.__rcell2
+
+    @property
+    def transform_c1_to_p1(self) -> Rotation:
+        """
+        scipy.spatial.transform.Rotation: The Cartesian rotation associated with ucell1 to ucell_prim1
+        """
+        return self.__transform_c1_to_p1
+
+    @property
+    def transform_c2_to_p2(self) -> Rotation:
+        """
+        scipy.spatial.transform.Rotation: The Cartesian rotation associated with ucell2 to ucell_prim2
+        """
+        return self.__transform_c2_to_p2
+
+    @property
+    def transform_p1_to_r1(self) -> Rotation:
+        """
+        scipy.spatial.transform.Rotation: The Cartesian rotation associated with ucell_prim1 to rcell1
+        """
+        return self.__transform_p1_to_r1
+
+    @property
+    def transform_p2_to_r2(self) -> Rotation:
+        """
+        scipy.spatial.transform.Rotation: The Cartesian rotation associated with ucell_prim2 to rcell2
+        """
+        return self.__transform_p2_to_r2
+
+    @property
+    def cutboxvector(self) -> str:
+        """str: The box vector that the grain boundary is positioned along"""
+        return self.__cutboxvector
+
+    @property
+    def cutindex(self) -> int:
+        """int: The integer index associated with the cutboxvector setting"""
+        return self.__cutindex
+
+    @property
+    def mults1(self) -> np.ndarray:
+        """numpy.NDArray: Three int size multipliers for the top grain."""
+        return self.__mults1
+
+    @mults1.setter
+    def mults1(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype=int)
+        assert value.shape == (3,)
+        self.__mults1 = value
+
+    @property
+    def mults2(self) -> np.ndarray:
+        """numpy.NDArray: Three int size multipliers for the bottom grain."""
+        return self.__mults2
+
+    @mults2.setter
+    def mults2(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype=int)
+        assert value.shape == (3,)
+        self.__mults2 = value
+
+    def identifymults(self,
+                      maxmult: int = 10,
+                      minwidth: float = 0.0,
+                      setvalues: bool = False
+                      ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Compares the in-plane vectors of rcell1 and rcell2 to determine optimum
+        system multipliers to minimize strain.
+
+        Parameters
+        ----------
+        maxmult : int, optional
+            The maximum size multiplier to use in searching for low strain
+            states for the in-plane box vectors.  Both grains will be searched
+            up to this max, so only one grain's multiplier is guaranteed to be
+            maxmult or less.  Default value is 10.
+        minwidth: float, optional
+            A minimum width that is used to determine the size multipliers for
+            the out-of-plane box vectors of the two grains.  This width limit is
+            independently applied to both grains (not the sum) and is taken in
+            the direction perpendicular to the grain boundary.  Default value
+            is 0.0, which sets the multipliers to +-1.
+        setvalues: bool, optional
+            If True, the identified mults1 and mults2 values will be saved to
+            the corresponding class attributes.  Default value is False.
+
+        Returns
+        -------
+        mults1 : numpy.ndarray
+            The suggested size multipliers to use with the top grain.
+        mults2 : numpy.ndarray
+            The suggested size multipliers to use with the bottom grain.
+        strains : numpy.ndarray
+            The estimated strains relative to the top grain that will result
+            from the two grains positioned together with the suggested
+            mults1 and mults2. Three values are given, one for each direction,
+            with the out-of-plane strain always being reported as zero.
+        """
+        strains = np.zeros(3)
+        mults1 = np.ones(3, dtype=int)
+        mults2 = np.ones(3, dtype=int)
+
+        for i in range(3):
+            if i == self.cutindex:
+                continue
+
+            length1 = np.linalg.norm(self.rcell1.box.vects[i])
+            length2 = np.linalg.norm(self.rcell2.box.vects[i])
+
+            # If lengths are equal, both mults are 1 and strains are zero
+            if length1 == length2:
+                continue
+
+            # Search for minimum strain configurations
+            mult1 = 0
+            mult2 = 0
+            strain = 999999
+            for multa in range(1, maxmult+1):
+
+                # Check multiples of length1
+                length = length1 * multa
+
+                # Compute strain and compare to current known minimum
+                multb = round(length / length2)
+                teststrain = (length - multb * length2) / length
+                if abs(teststrain) < abs(strain) and multb > 0:
+                    mult1 = multa
+                    mult2 = multb
+                    strain = teststrain
+
+                    if strain == 0.0:
+                        break
+
+                # Check multiples of length2
+                length = length2 * multa
+
+                # Compute strain and compare to current known minimum
+                multb = round(length / length1)
+                teststrain = (multb * length1 - length) / (multb * length1)
+
+                if abs(teststrain) < abs(strain) and multb > 0:
+                    mult1 = multb
+                    mult2 = multa
+                    strain = teststrain
+
+                    if strain == 0.0:
+                        break
+
+            strains[i] = strain
+            mults1[i] = mult1
+            mults2[i] = mult2
+
+        # Set out-of-plane multipliers based on minwidth
+        if minwidth == 0.0:
+            mults1[self.cutindex] = 1
+            mults2[self.cutindex] = -1
+        else:
+            width1 = self.rcell1.box.vects[self.cutindex, self.cutindex]
+            mults1[self.cutindex] = ceil(minwidth / width1)
+            width2 = self.rcell1.box.vects[self.cutindex, self.cutindex]
+            mults2[self.cutindex] = - ceil(minwidth / width2)
+
+        if setvalues:
+            self.mults1 = mults1
+            self.mults2 = mults2
+
+        return mults1, mults2, strains
+
+    def boundary(self,
+                 mults1: Optional[npt.ArrayLike] = None,
+                 mults2: Optional[npt.ArrayLike] = None,
+                 maxmult: Optional[int] = None,
+                 minwidth: Optional[float] = None,
+                 freesurface: bool = False,
+                 straintype: str = 'top',
+                 shift1: float = 0.0,
+                 shift2: float = 0.0,
+                 deleter: float = 0.1,
+                 deletefrom: str = 'top'):
+        """
+        Generates a phase/grain boundary configuration.
+
+        Parameters
+        ----------
+        mults1 : array-like object, optional
+            Three int size multipliers to use with the top grain.  If given,
+            mults2 is required and maxmults and minwidth cannot be given.  The
+            mults1 class attribute will be updated to this value by the method.
+            If mults1 is not given, then either maxmults must be given or the
+            mults1, mults2 class attributes must be set prior to calling.
+        mults2 : array-like object, optional
+            Three int size multipliers to use with the bottom grain.  If given,
+            mults1 is required and maxmults and minwidth cannot be given.  The
+            mults2 class attribute will be updated to this value by the method.
+            If mults2 is not given, then either maxmults must be given or the
+            mults1, mults2 class attributes must be set prior to calling.
+        maxmult : int, optional
+            The maximum size multiplier to use in searching for low strain
+            states for the in-plane box vectors.  Both grains will be searched
+            up to this max, so only one grain's multiplier is guaranteed to be
+            maxmult or less.  If given, mults1 and mults2 cannot be given.  If
+            not given, then mults1 and mults2 must either be given or
+            previously set as class attributes.
+        minwidth: float, optional
+            A minimum width that is used to determine the size multipliers for
+            the out-of-plane box vectors of the two grains.  This width limit is
+            independently applied to both grains (not the sum) and is taken in
+            the direction perpendicular to the grain boundary.  Only allowed if
+            maxmult is given.  If not given with maxmult, then will default to
+            0.0.
+        freesurface: bool, optional
+            Indicates if the system is non-periodic along the cutboxvector and
+            therefore contains a free surface (value of True) or if all box
+            vectors are periodic and the system contains two boundaries (value
+            of False).  Default value is False.
+        straintype: str, optional
+            Indicates how the lattice mismatch strain is applied.  'top' and
+            'bottom' will strain only the associated grains while 'both' will
+            divide the strain between both grains.
+        shift1: float, optional
+            A rigid body shift to apply along one of the two in-plane box
+            vectors.  This is taken relative to the rcell's a vector or b
+            vector if cutboxvector='a', so it should range between 0 and 1.
+            Default value is 0.0.
+        shift2: float, optional
+            A rigid body shift to apply along one of the two in-plane box
+            vectors.  This is taken relative to the rcell's c vector or b
+            vector if cutboxvector='c', so it should range between 0 and 1.
+            Default value is 0.0.
+        deleter: float, optional
+            Any atoms in the separate grains closer than this distance will
+            have one atom of the pair deleted to prevent overlapping atoms.
+            Varying this value can possibly result in a lower energy
+            configuration.  Default value is 0.1.
+        deletefrom: str, optional
+            Indicates which grain 'top' or 'bottom' the atoms found with
+            deletewidth will be deleted from.  Typically doesn't matter
+            for symmetric tilt grain boundaries but does matter for
+            asymmetric grain boundaries or phase boundaries.
+        
+        Returns
+        -------
+        atomman.System
+            The grain/phase boundary atomic configuration
+        natoms1 : int
+            The number of atoms in the top grain.  This can be used to determine
+            which atoms are in which grain as the first natoms1 atoms in the
+            returned system will be in the top grain, and the rest in the bottom
+            grain.
+        """
+        if mults1 is not None or mults2 is not None:
+            assert mults1 is not None and mults2 is not None, (
+                'mults1 and mults2 must be given together')
+            assert maxmult is None and minwidth is None, (
+                'maxmult and minwidth cannot be given with mults1, mults2')
+            self.mults1 = mults1
+            self.mults2 = mults2
+
+        elif maxmult is not None:
+            if minwidth is None:
+                minwidth = 0.0
+            self.identifymults(maxmult=maxmult, minwidth=minwidth, setvalues=True)
+
+        elif minwidth is not None:
+            raise ValueError('maxmult must be given with minwidth')
+
+        # Create systems for each grain
+        assert not np.any(np.isclose(self.mults1, np.zeros(3))), 'mults cannot be zero'
+        assert not np.any(np.isclose(self.mults2, np.zeros(3))), 'mults cannot be zero'
+        assert self.mults1[self.cutindex] > 0, 'out-of-plane mult for top grain must be positive'
+        assert self.mults2[self.cutindex] < 0, 'out-of-plane mult for bottom grain must be negative'
+        system1 = self.rcell1.supersize(*self.mults1)
+        system2 = self.rcell2.supersize(*self.mults2)
+
+        # Build system
+        self.applystrain(system1, system2, straintype)
+        system = self.mergesystems(system1, system2, freesurface)
+        self.applyshift(system, shift1, shift2, system1.natoms)
+        newsystem, natoms1 = self.deleteoverlaps(system, deleter, deletefrom, system1.natoms)
+
+        return newsystem, natoms1
+
+    def applystrain(self, system1, system2, straintype):
+        """
+        Adjust the in-plane box vectors to apply the necessary strain for lattice
+        compatibility.
+        """
+        if straintype == 'top':
+            # Strain in-plane vects of top grain to match bottom grain vects
+            vects = system2.box.vects
+            vects[self.cutindex] = system1.box.vects[self.cutindex]
+            system1.box_set(vects=vects, origin=system1.box.origin, scale=True)
+
+        elif straintype == 'bottom':
+            # Strain in-plane vects of bottom grain to match top grain vects
+            vects = system1.box.vects
+            vects[self.cutindex] = system2.box.vects[self.cutindex]
+            system2.box_set(vects=vects, origin=system2.box.origin, scale=True)
+
+        elif straintype == 'both':
+            # Average vects (works as in-plane vects are parallel)
+            vects = (system1.box.vects + system2.box.vects) / 2
+
+            # Change vects while retaining out-of-plane vects and origins.
+            vects[self.cutindex] = system1.box.vects[self.cutindex]
+            system1.box_set(vects=vects, origin=system1.box.origin, scale=True)
+            vects[self.cutindex] = system2.box.vects[self.cutindex]
+            system2.box_set(vects=vects, origin=system2.box.origin, scale=True)
+
+        else:
+            raise ValueError('Unknown straintype value: allowed values are top, bottom, or both')
+
+    def mergesystems(self, system1, system2, freesurface):
+        """
+        """
+        # Combine atoms
+        system = system1.atoms_extend(system2.atoms)
+
+        # Increase box size
+        vects = system.box.vects
+        vects[self.cutindex] += system2.box.vects[self.cutindex]
+        system.box_set(vects=vects, origin=system2.box.origin)
+
+        if freesurface:
+            system.pbc[self.cutindex] = False
+
+        return system
+
+    def applyshift(self, system, shift1, shift2, natoms1):
+        """
+        """
+        if self.cutboxvector == 'a':
+            shift = shift1 * system.box.bvect + shift2 * system.box.cvect
+        elif self.cutboxvector == 'b':
+            shift = shift1 * system.box.avect + shift2 * system.box.cvect
+        elif self.cutboxvector == 'c':
+            shift = shift1 * system.box.avect + shift2 * system.box.bvect
+
+        system.atoms.pos[:natoms1] += shift
+        system.wrap()
+
+    def deleteoverlaps(self, system, deleter, deletefrom, natoms1):
+        """
+        """
+        if deleter == 0.0:
+            return system, natoms1
+
+        # Build neighborlist
+        cutoff = 1.2
+        if deleter > cutoff:
+            cutoff = deleter + 0.2
+        nlist = system.neighborlist(cutoff=cutoff)
+
+        dup = set()
+        for i in range(natoms1):
+            if nlist.coord[i] == 0:
+                continue
+
+            dmag = system.dmag(i, nlist[i])
+            if nlist.coord[i] == 1:
+                if dmag < deleter:
+                    if deletefrom == 'top':
+                        dup.add(i)
+                    elif deletefrom == 'bottom':
+                        dup.update(nlist[i])
+            else:
+                dups = nlist[i][dmag < deleter]
+
+                if deletefrom == 'top' and np.any(dups >= natoms1):
+                    dup.add(i)
+                elif deletefrom == 'bottom':
+                    dup.update(dups[dups >= natoms1])
+
+        keepindex = [x for i, x in enumerate(range(system.natoms)) if i not in dup]
+        newsystem = system.atoms_ix[keepindex]
+
+        if deletefrom == 'top':
+            natoms1 = natoms1 - len(dup)
+
+        return newsystem, natoms1
+
+    def iterboundaryshift(self,
+                          mults1: Optional[npt.ArrayLike] = None,
+                          mults2: Optional[npt.ArrayLike] = None,
+                          maxmult: Optional[int] = None,
+                          minwidth: Optional[float] = None,
+                          freesurface: bool = False,
+                          straintype = 'top',
+                          shifts1 = 0.0,
+                          shifts2 = 0.0,
+                          deleters = 0.1,
+                          deletefrom = 'top'):
+        """
+        Generates multiple proposed phase/grain boundary configurations for the
+        same boundary orientation where the in-plane shifts are varied as well
+        as which overlapping atoms are deleted.
+
+        Parameters
+        ----------
+        mults1 : array-like object, optional
+            Three int size multipliers to use with the top grain.  If given,
+            mults2 is required and maxmults and minwidth cannot be given.  The
+            mults1 class attribute will be updated to this value by the method.
+            If mults1 is not given, then either maxmults must be given or the
+            mults1, mults2 class attributes must be set prior to calling.
+        mults2 : array-like object, optional
+            Three int size multipliers to use with the bottom grain.  If given,
+            mults1 is required and maxmults and minwidth cannot be given.  The
+            mults2 class attribute will be updated to this value by the method.
+            If mults2 is not given, then either maxmults must be given or the
+            mults1, mults2 class attributes must be set prior to calling.
+        maxmult : int, optional
+            The maximum size multiplier to use in searching for low strain
+            states for the in-plane box vectors.  Both grains will be searched
+            up to this max, so only one grain's multiplier is guaranteed to be
+            maxmult or less.  If given, mults1 and mults2 cannot be given.  If
+            not given, then mults1 and mults2 must either be given or
+            previously set as class attributes.
+        minwidth: float, optional
+            A minimum width that is used to determine the size multipliers for
+            the out-of-plane box vectors of the two grains.  This width limit is
+            independently applied to both grains (not the sum) and is taken in
+            the direction perpendicular to the grain boundary.  Only allowed if
+            maxmult is given.  If not given with maxmult, then will default to
+            0.0.
+        freesurface: bool, optional
+            Indicates if the system is non-periodic along the cutboxvector and
+            therefore contains a free surface (value of True) or if all box
+            vectors are periodic and the system contains two boundaries (value
+            of False).  Default value is False.
+        straintype: str, optional
+            Indicates how the lattice mismatch strain is applied.  'top' and
+            'bottom' will strain only the associated grains while 'both' will
+            divide the strain between both grains.
+        shifts1: int, float, or list, optional
+            Indicates which rigid body shifts to apply along one of the two
+            in-plane box vectors.  This is taken relative to the rcell's a
+            vector or b vector if cutboxvector='a', so shift values should
+            range between 0 and 1.  Giving a single float value will only
+            perform one shift while giving a list of floats will iterate over
+            all values.  If an int is given, then that number of equally-
+            spaced shifts will be explored between 0 <= shift1 < 1.  Default
+            value is 0.0 (no shift, no iteration).
+        shifts2: int, float, or list, optional
+            Indicates which rigid body shifts to apply along one of the two
+            in-plane box vectors.  This is taken relative to the rcell's c
+            vector or b vector if cutboxvector='c', so shift values should
+            range between 0 and 1.  Giving a single float value will only
+            perform one shift while giving a list of floats will iterate over
+            all values.  If an int is given, then that number of equally-
+            spaced shifts will be explored between 0 <= shift1 < 1.  Default
+            value is 0.0 (no shift, no iteration).
+        deleters: float or list, optional
+            One or more interatomic spacing cutoffs to explore for
+            identifying overlapping atoms between the two grains.  If multiple
+            values are given, systems are yielded only if they differ from
+            the previous system with the same in-plane shift.  Default value is
+            0.1 (one value, no iteration).
+        deletefrom: str, optional
+            Indicates which grain 'top' or 'bottom' the atoms found with
+            deletewidth will be deleted from.  A value of 'both' will iterate
+            over both top and bottom deletions.  Typically doesn't matter
+            for symmetric tilt grain boundaries but does matter for
+            asymmetric grain boundaries or phase boundaries.
+        
+        Yields
+        -------
+        atomman.System
+            The grain/phase boundary atomic configuration
+        natoms1 : int
+            The number of atoms in the top grain.  This can be used to determine
+            which atoms are in which grain as the first natoms1 atoms in the
+            returned system will be in the top grain, and the rest in the bottom
+            grain.
+        """
+
+        # Set up values to iterate over
+        shifts1 = self.interpret_shifts(shifts1)
+        shifts2 = self.interpret_shifts(shifts2)
+        deleters = [float(i) for i in iaslist(deleters)]
+        if deletefrom == 'both':
+            deletefroms = ['top', 'bottom']
+        else:
+            deletefroms = [deletefrom]
+
+        # Iterate over all combos
+        for shift1 in shifts1:
+            for shift2 in shifts2:
+                for deletefrom in deletefroms:
+
+                    # deletewidth must be inner loop to do the natoms check
+                    natoms = -999999
+                    for deleter in deleters:
+                        system, natoms1 = self.boundary(mults1=mults1,
+                                                        mults2=mults2,
+                                                        maxmult=maxmult,
+                                                        minwidth=minwidth,
+                                                        freesurface=freesurface,
+                                                        straintype=straintype,
+                                                        shift1=shift1,
+                                                        shift2=shift2,
+                                                        deleter=deleter,
+                                                        deletefrom=deletefrom)
+
+                        # Only yield systems where a different number of atoms was deleted
+                        if system.natoms != natoms:
+                            natoms = system.natoms
+                            yield system, natoms1
+
+    def interpret_shifts(self, val):
+        """
+        If int, do equal shifts in range [0, 1).
+        If float or == 0, only do that value.
+        If list, do those values
+        """
+        # Test for int value
+        try:
+            assert int(val) == val
+            assert val > 0
+        except (AssertionError, ValueError, TypeError):
+            pass
+        else:
+            return np.linspace(0, 1, num=int(val), endpoint=False)
+
+        return [float(i) for i in iaslist(val)]
+
+
+def interpret_rotation_uvws(*uvws,
+                            conventional_setting='p'):
+    """
+    Interprets the three rotation uvws for a crystal.
+    
+    Parameters
+    ----------
+    uvws : list, array
+        The three Miller uvw vectors or Miller-Bravais uvtw vectors that the
+        unit cell should be rotated to align with.  The three vectors can
+        either be given directly or within a list.  Each value in the list can
+        itself be an array-like object or a str representation of a Miller
+        vector.
+    conventional_setting : str, optional
+        Indicates the conventional lattice setting associated with the Miller
+        vectors given.  Default value is 'p' for a primitive unit cell.
+        
+    Returns
+    -------
+    uvws_conv : numpy.ndarray
+        3x3 array of Miller vector indices relative to the conventional unit cell.
+    uvws_prim : numpy.ndarray
+        3x3 array of Miller vector indices relative to the primitive unit cell.
+    
+    Raises
+    ------
+    ValueError
+        If the generated uvws_prim indices are not integer values.    
+    """
+    # Check for valid len of uvws
+    if len(uvws) == 1:
+        uvws = uvws[0] 
+    if len(uvws) != 3:
+        raise ValueError('invalid uvws: 3 values expected')
+    
+    # Convert given uvws into uvws_conv array
+    uvws_conv = []
+    for uvw in uvws:
+        if isinstance(uvw, str):
+            uvw = miller.fromstring(uvw)
+        else:
+            uvw = np.asarray(uvw, dtype=float)
+            
+        if uvw.shape == (4,):
+            uvw = miller.vector4to3(uvw)
+        elif uvw.shape != (3,):
+            raise ValueError('invalid uvws: each uvw must have 3 or 4 indices')
+        
+        uvws_conv.append(uvw)
+    uvws_conv = np.array(uvws_conv)
+    
+    
+    # Convert uvws1 to the primitive cell
+    uvws_prim = miller.vector_conventional_to_primitive(uvws_conv, setting=conventional_setting)
+    
+    # Check that uvws_prim are ints
+    uvws_prim_int = np.array(np.rint(uvws_prim), dtype=int)
+    if np.allclose(uvws_prim, uvws_prim_int):
+        uvws_prim = uvws_prim_int
+    else:
+        raise ValueError('primitive Miller vector indices are not all ints, therefore they are not lattice vectors!')
+    
+    return uvws_conv, uvws_prim
+
+def clean_wrap(system, atol=1e-7):
+    """
+    Wrap atoms around periodic boundaries cleanly
+
+    Parameters
+    ----------
+    system : atomman.System
+        The atomic system to wrap the atoms for.
+    atol : float
+        The absolute tolerance to use for identifying atoms on a boundary.
+        Default value is 1e-7.
+    """
+    # Safely wrap atoms into the rcells
+    system.atoms.pos += atol
+    system.wrap()
+    system.atoms.pos -= atol
+    system.atoms.pos[np.isclose(system.atoms.pos, 0.0, atol=atol, rtol=0)] = 0

atomman/source/atomman/defect/DifferentialDisplacement.py

@@ -0,0 +1,733 @@
+# coding: utf-8
+# Standard Python libraries
+from re import A
+from typing import Optional, Tuple, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://matplotlib.org/
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+from matplotlib import cm
+
+# atomman imports
+from ..tools import axes_check
+from .. import Box, System, NeighborList
+from . import Strain
+from ..plot import interpolate_contour
+
+class DifferentialDisplacement():
+    def __init__(self,
+                 system0: System,
+                 system1: System,
+                 neighbors: Optional[NeighborList] = None,
+                 cutoff: Optional[float] = None,
+                 reference: int = 1):
+        """
+        Class initializer.  Calls solve if either neighbors or cutoff are given.
+        
+        Parameters
+        ----------
+        system0 : atomman.system
+            The base/reference system to use.
+        system1 : atomman.system
+            The defect/current system to use.
+        neighbors : atomman.NeighborList, optional
+            The neighbor list to use.  
+        cutoff : float, optional
+            Cutoff distance for computing a neighbor list. If reference = 0, then system_0
+            will be used to generate the list. If reference = 1, then system_1 will be
+            used to generate the list.
+        reference : int, optional
+            Indicates which of the two systems should be used for the plotting
+            reference: 0 or 1. If 0, then system_0's atomic positions will be
+            used for the calculation and neighbors should be for system_0.  If
+            1 (default), then system_1's atomic positions will be used
+            for the calculation and neighbors should be for system_1.   
+        """
+        
+        if neighbors is not None or cutoff is not None:
+            self.solve(system0, system1, neighbors=neighbors, cutoff=cutoff, reference=reference)
+        else:
+            assert system0.natoms == system1.natoms
+            
+            self.__system0 = system0
+            self.__system1 = system1
+            self.reference = reference
+            self.__neighbors = None
+            self.__ddvectors = None
+            self.__arrowcenters = None
+            self.__arrowuvectors = None
+    
+    @property
+    def reference(self) -> int:
+        """int : Indicates which system (0 or 1) is used as the reference."""
+        return self.__reference
+
+    @reference.setter
+    def reference(self, value: int):
+        assert value == 0 or value == 1, 'reference must be 0 or 1'
+        self.__reference = value    
+    
+    @property
+    def system0(self) -> System:
+        """atomman.System : The defect-free base system."""
+        return self.__system0
+    
+    @property
+    def system1(self) -> System:
+        """atomman.System : The defect containing system."""
+        return self.__system1
+    
+    @property
+    def neighbors(self) -> NeighborList:
+        """atomman.NeighborList : The list of neighbors identified for the reference system."""
+        return self.__neighbors
+    
+    @property
+    def ddvectors(self) -> Optional[np.ndarray]:
+        """numpy.array or None : The computed differential displacement vectors."""
+        return self.__ddvectors
+    
+    @property
+    def arrowcenters(self) -> Optional[np.ndarray]:
+        """numpy.array or None : The identified center positions for the ddvectors."""
+        return self.__arrowcenters
+    
+    @property
+    def arrowuvectors(self) -> Optional[np.ndarray]:
+        """numpy.array or None : The unit vectors between all pairs of atoms for which the ddvectors have been computed."""
+        return self.__arrowuvectors
+    
+    def solve(self,
+              system0: Optional[System] = None,
+              system1: Optional[System] = None,
+              neighbors: Optional[NeighborList] = None,
+              cutoff: Optional[float] = None,
+              reference: Optional[int] = None):
+        """
+        Solves the differential displacement vectors.
+        
+        Parameters
+        ----------
+        system0 : atomman.system, optional
+            The base/reference system to use.
+        system1 : atomman.system, optional
+            The defect/current system to use.
+        neighbors : atomman.NeighborList, optional
+            The neighbor list to use.  
+        cutoff : float, optional
+            Cutoff distance for computing a neighbor list. If reference = 0, then system_0
+            will be used to generate the list. If reference = 1, then system_1 will be
+            used to generate the list.
+        reference : int, optional
+            Indicates which of the two systems should be used for the plotting reference: 0 or 1.
+            If 0, then system0's atomic positions will be used for the calculation and
+            neighbors should be for system0.  If 1, then system1's atomic positions will be used
+            for the calculation and neighbors should be for system1.  Default value is
+            whatever was set when the object was initialized. 
+        """
+        # Handle parameters
+        if system0 is not None:
+            self.__system0 = system0
+        else:
+            system0 = self.system0
+        if system1 is not None:
+            self.__system1 = system1
+        else:
+            system1 = self.system1
+        assert system0.natoms == system1.natoms
+        
+        if reference is None:
+            reference = self.reference
+        else:
+            self.reference = reference
+        if reference == 0:
+            refsystem = system0
+        else:
+            refsystem = system1
+        
+        if neighbors is None:
+            if cutoff is not None:
+                self.__neighbors = neighbors = refsystem.neighborlist(cutoff=cutoff)
+            else:
+                if self.neighbors is not None:
+                    neighbors = self.neighbors
+                else:
+                    raise ValueError('Either neighbors or cutoff must be given')
+        else:
+            self.__neighbors = neighbors
+        
+        all_ddvectors = []
+        all_arrowcenters = []
+        all_arrowuvectors = []
+        
+        # Loop over all atoms i in ref system
+        for i in np.arange(refsystem.natoms):
+            neighs = neighbors[i]
+            if len(neighs) == 0:
+                continue
+            
+            # Compute distance vectors between atom i and its neighbors for both systems
+            dvectors0 = system0.dvect(int(i), neighs)
+            dvectors1 = system1.dvect(int(i), neighs)
+            if dvectors0.shape == (3,):
+                dvectors0.shape = (1,3)
+                dvectors1.shape = (1,3)
+
+            # Compute differential displacement vectors
+            ddvectors = dvectors1 - dvectors0
+
+            # Compite center points and direction vectors
+            if reference == 0:
+                arrowcenters = system0.atoms.pos[i] + dvectors0 / 2
+                arrowuvectors = dvectors0 / np.linalg.norm(dvectors0, axis=1)[:,np.newaxis]    
+            else:    
+                arrowcenters = system1.atoms.pos[i] + dvectors1 / 2
+                arrowuvectors = dvectors1 / np.linalg.norm(dvectors1, axis=1)[:,np.newaxis]
+                
+            # Append calculation values to associated lists            
+            all_ddvectors.append(ddvectors)
+            all_arrowcenters.append(arrowcenters)
+            all_arrowuvectors.append(arrowuvectors)
+        
+        # Save computed values to object properties 
+        self.__ddvectors = np.concatenate(all_ddvectors)
+        self.__arrowcenters = np.concatenate(all_arrowcenters)
+        self.__arrowuvectors = np.concatenate(all_arrowuvectors)
+        
+    def plot(self,
+             component: Union[str, npt.ArrayLike],
+             ddmax: Optional[float],
+             plotxaxis: Union[str, npt.ArrayLike] = 'x',
+             plotyaxis: Union[str, npt.ArrayLike] = 'y',
+             xlim: Optional[tuple] = None,
+             ylim: Optional[tuple] = None,
+             zlim: Optional[tuple] = None,
+             arrowscale: float = 1,
+             arrowwidth: float = 0.005,
+             use0z: bool = False,
+             atomcolor: Union[str, list, None] = None,
+             atomcmap: Union[str, list, None] = None,
+             atomsize: float = 0.5,
+             figsize: int = 10,
+             matplotlib_axes: Optional[plt.axes] = None
+             ) -> Optional[plt.figure]:
+
+        r"""
+        Creates a matplotlib figure of a differential displacement map.  Atom
+        positions are represented as circles, while the selected components of the
+        differential displacement vectors are plotted as arrows.
+        
+        Parameters
+        ----------
+        component : str or array-like object
+            Indicates the component(s) of the differential displacement to plot.
+            Values of 'x', 'y', or 'z' will plot the component along that
+            Cartesian direction.  A value of 'projection' will plot the
+            differential displacement vectors as projected onto the plotting
+            plane, thereby showing the two components perpendicular to the line
+            direction.  If a 3D vector is given, then the component parallel to
+            that direction will be used.
+        ddmax : float or None
+            The maximum differential displacement value allowed. Values will be
+            kept between +-ddmax by wrapping values with larger absolute values
+            around by adding/subtracting 2*ddmax. Typically, this is set to be
+            \|b\|/2, but can be defect-specific. For instance, fcc a/2<110>
+            dislocations and basal hcp dislocations are typically plotted with
+            ddmax=\|b\|/4.  If set to None, then no wrapping is done.
+        plotxaxis : str or array-like object, optional
+            Indicates the Cartesian direction associated with the system's atomic
+            coordinates to align with the plotting x-axis.  Values are either 3D
+            unit vectors, or strings 'x', 'y', or 'z' for the Cartesian axes
+            directions.  plotxaxis and plotyaxis must be orthogonal.  Default value
+            is 'x' = [1, 0, 0].
+        plotyaxis : str or array-like object, optional
+            Indicates the Cartesian direction associated with the system's atomic
+            coordinates to align with the plotting y-axis.  Values are either 3D
+            unit vectors, or strings 'x', 'y', or 'z' for the Cartesian axes
+            directions.  plotxaxis and plotyaxis must be orthogonal.  Default value
+            is 'y' = [0, 1, 0].
+        xlim : tuple, optional
+            The minimum and maximum coordinates along the plotting x-axis to
+            include in the fit.  Values are taken in the specified length_unit.
+            If not given, then the limits are set based on min and max atomic
+            coordinates along the plotting axis.
+        ylim : tuple, optional
+            The minimum and maximum coordinates along the plotting y-axis to
+            include in the fit.  Values are taken in the specified length_unit.
+            If not given, then the limits are set based on min and max atomic
+            coordinates along the plotting axis.
+        zlim : tuple, optional
+            The minimum and maximum coordinates normal to the plotting axes
+            (i.e. plotxaxis X plotyaxis) to include in the fit.  Values are taken
+            in the specified length_unit.  The optimum zlim should encompass only
+            a single periodic slice.  If not given, then the limits are set
+            based on min and max atomic coordinates along the axis.
+        arrowscale : float, optional
+            Scaling factor for the magnitude of the differential displacement
+            arrows.  Default value is 1: no scaling, vectors are in units of length.
+            For major components, this is often set such that the max differential
+            displacement component after wrapping (see ddmax) is scaled to the
+            distance between the atom pairs in the plot.  For minor components, this
+            is often set to a large value simply to make the components visible.
+        arrowwidth : float, optional
+            Scaling factor to use for the width of the plotted arrows. Default value is
+            0.005 = 1/200.
+        use0z : bool, optional
+            If False (default), the z coordinates from the reference system will be
+            used for zlim and atomcmap colors. If True, the z coordinates will be
+            used from system0 even if system1 is the reference system.
+        atomcolor : str or list, optional
+            Matplotlib color name(s) to use to display the atoms.  If str, that
+            color will be assigned to all atypes.  If list, must give a color value
+            or None for each atype.  Default value (None) will use cmap instead.
+            Note: atomcolor and atomcmap can be used together as long as exactly
+            one color or cmap is given for each unique atype.
+        atomcmap : str or list, optional
+            Matplotlib colormap name(s) to use to display the atoms.  Atoms will
+            be colored based on their initial positions and scaled using zlim. If
+            str, that cmap will be assigned to all atypes.  If list, must give a 
+            cmap value or None for each atype.  Default value (None) will use 'hsv'
+            cmap.  Note: atomcolor and atomcmap can be used together as long as
+            exactly one color or cmap is given for each unique atype.
+        atomsize : float, optional
+            The circle radius size to use for the plotted atom positions in units of
+            length.  Default value is 0.5.
+        figsize : float or tuple, optional
+            Specifies the size of the figure to create in inches.  If a single value
+            is given, it will be used for the figure's width, and the height will be
+            scaled based on the xlim and ylim values.  Alternatively, both the width
+            and height can be set by passing a tuple of two values, but the plot will
+            not be guaranteed to be "regular" with respect to length dimensions.
+        matplotlib_axes : matplotlib.Axes.axes, optional
+            An existing matplotlib axes object. If given, the differential displacement
+            plot will be added to the specified axes of an existing figure.  This
+            allows for subplots to be constructed.  Note that figsize will be ignored
+            as the figure would have to be created beforehand and no automatic
+            optimum scaling of the figure's dimensions will occur.
+            
+        Returns
+        -------
+        matplotlib.Figure
+            The generated figure.  Not returned if matplotlib_axes is given.
+        """
+
+        ###################### Parameter and plot setup ########################
+
+        # Interpret plot axis values
+        plotxaxis = self.__plotaxisoptions(plotxaxis)
+        plotyaxis = self.__plotaxisoptions(plotyaxis)
+
+        # Build transformation matrix, T, from plot axes.
+        T = axes_check([plotxaxis, plotyaxis, np.cross(plotxaxis, plotyaxis)])
+
+        # Extract positions and transform using T        
+        if self.reference == 0:        
+            atompos = np.inner(self.system0.atoms.pos, T)
+            refsystem = self.system0
+        else:
+            atompos = np.inner(self.system1.atoms.pos, T)
+            refsystem = self.system1
+            if use0z:
+                pos0 = np.inner(self.system0.atoms.pos, T)
+                atompos[:, 2] = pos0[:, 2]
+
+        # Set default plot limits
+        if xlim is None:
+            xlim = (atompos[:, 0].min(), atompos[:, 0].max())
+        if ylim is None:
+            ylim = (atompos[:, 1].min(), atompos[:, 1].max())
+        if zlim is None:
+            zlim = (atompos[:, 2].min(), atompos[:, 2].max()) 
+
+        # Define box for identifying only points inside
+        plotbox = Box(xlo = xlim[0] - 5, xhi = xlim[1] + 5,
+                      ylo = ylim[0] - 5, yhi = ylim[1] + 5,
+                      zlo = zlim[0], zhi = zlim[1])
+            
+        # Set plot height if needed
+        if isinstance(figsize, (int, float)):
+            dx = xlim[1] - xlim[0]
+            dy = ylim[1] - ylim[0]
+            figsize = (figsize, figsize * dy / dx)
+
+        # Initial plot setup and parameters
+        if matplotlib_axes is None:
+            fig = plt.figure(figsize=figsize, dpi=72)
+            ax1 = fig.add_subplot(111)
+        else:
+            ax1 = matplotlib_axes
+        ax1.axis([xlim[0], xlim[1], ylim[0], ylim[1]])
+        
+        # Handle atomcolor and atomcmap values
+        atomcolor, atomcmap = self.__atomcoloroptions(atomcolor, atomcmap)
+
+        ######################## Add atom circles to plot ##############################
+        
+        # Loop over all atoms i in plotting box
+        for i in np.arange(refsystem.natoms)[plotbox.inside(atompos)]:
+            atype = refsystem.atoms.atype[i]
+            atype_index = refsystem.atypes.index(atype)
+
+            # Plot a circle for atom i
+            if atomcmap[atype_index] is not None:
+                color = atomcmap[atype_index]((atompos[i, 2] - zlim[0]) / (zlim[1] - zlim[0]))
+            elif atomcolor[atype_index] is not None:
+                color = atomcolor[atype_index]
+            else:
+                color = None
+            if color is not None:
+                ax1.add_patch(mpatches.Circle(atompos[i, :2], atomsize, fc=color, ec='k'))
+
+        ######################## Arrow setup ##############################
+        
+        # Build arrows based on component
+        arrowlengths, arrowcenters = self.__buildarrows(T, plotbox, component, ddmax)
+        
+        # Scale arrows
+        arrowlengths = arrowscale * arrowlengths
+        
+        # Compute arrow widths based on lengths
+        arrowwidths = arrowwidth * (arrowlengths[:,0]**2 + arrowlengths[:,1]**2)**0.5
+
+        # Plot the arrows
+        for center, length, width in zip(arrowcenters, arrowlengths, arrowwidths):
+            if width > 1e-7:
+                ax1.quiver(center[0], center[1], length[0], length[1],
+                           pivot='middle', angles='xy', scale_units='xy',
+                           scale=1, width=width, minshaft=2)
+        
+        if matplotlib_axes is None:
+            return fig
+    
+    def __plotaxisoptions(self, plotaxis):
+        """Internal method for handling plotxaxis and plotyaxis values"""
+        
+        # Give numeric values for str plot axis terms
+        if plotaxis == 'x':
+            plotaxis = [1.0, 0.0, 0.0]
+        elif plotaxis == 'y':
+            plotaxis = [0.0, 1.0, 0.0]
+        elif plotaxis == 'z':
+            plotaxis = [0.0, 0.0, 1.0]
+        
+        # Convert to numpy array
+        return np.asarray(plotaxis, dtype=float)
+    
+    def __atomcoloroptions(self, atomcolor, atomcmap):
+        """Internal method for handling atomcolor and atomcmap options"""
+        
+        # Identify number of atom types in the reference system
+        if self.reference == 0:
+            natypes = self.system0.natypes
+        else:
+            natypes = self.system1.natypes
+        
+        # Set default atomcmap
+        if atomcolor is None and atomcmap is None:
+            atomcmap = 'hsv'
+
+        # Normalize atomcolor values
+        if isinstance(atomcolor, str):
+            atomcolor = [atomcolor for i in range(natypes)]
+        elif atomcolor is None:
+            atomcolor = [None for i in range(natypes)]
+        else:
+            atomcolor = list(atomcolor)
+            if len(atomcolor) != natypes:
+                raise ValueError('Invalid number of atomcolor values')
+
+        # Normalize atomcmap values
+        if isinstance(atomcmap, str):
+            atomcmap = [atomcmap for i in range(natypes)]
+        elif atomcmap is None:
+            atomcmap = [None for i in range(natypes)]
+        else:
+            atomcmap = list(atomcmap)
+            if len(atomcmap) != natypes:
+                raise ValueError('Invalid number of atomcmap values')
+        
+        # Check that no atype has both atomcmap and atomcolor
+        for color, cmap in zip(atomcolor, atomcmap):
+            if color is not None and cmap is not None:
+                raise ValueError('atomcmap and atomcolor cannot both be given for the same atype')
+        
+        # Convert atomcmap str values to color map objects
+        for ic in range(natypes):
+            if atomcmap[ic] is not None:    
+                atomcmap[ic] = cm.get_cmap(atomcmap[ic])
+        
+        return atomcolor, atomcmap
+    
+    def __buildarrows(self, T, plotbox, component, ddmax):
+        """Internal method for building the parameters for plotting the arrows"""
+        
+        # Manage component
+        if isinstance(component, str):
+            if component == 'x':
+                component = np.array([1.0, 0.0, 0.0])
+            elif component == 'y':
+                component = np.array([0.0, 1.0, 0.0])
+            elif component == 'z':
+                component = np.array([0.0, 0.0, 1.0])
+            elif component != 'projection':
+                raise ValueError('Invalid component style: must be x, y, z, projection, or numpy array')
+        else:
+            component = np.asarray(component, dtype=float)
+            assert component.shape == (3,), 'Invalid numeric component: must be a 3D vector'
+            component = component / np.linalg.norm(component)
+            
+        # Transform arrow-related vectors
+        ddvectors = np.inner(self.ddvectors, T)
+        arrowcenters = np.inner(self.arrowcenters, T)
+        arrowuvectors = np.inner(self.arrowuvectors, T)
+                
+        # Identify only vectors in ploting box
+        inbounds = plotbox.inside(arrowcenters)
+        ddvectors = ddvectors[inbounds]
+        arrowcenters = arrowcenters[inbounds]
+        arrowuvectors = arrowuvectors[inbounds]
+
+        # Build arrows for the xy component option
+        if isinstance(component, str) and component == 'projection':
+            
+            # Arrows are in-plane vector components
+            ddcomponents = (ddvectors[:,0]**2 + ddvectors[:,1]**2)**0.5
+            arrowuvectors = ddvectors[:, :2] / ddcomponents[:,np.newaxis]
+            
+            # Scheme for direction uniqueness (not sure what other projects use?)
+            arrowuvectors[ddvectors[:, 2] > 0] *= -1
+            
+            # Normalize ddcomponents to be between +-ddmax
+            if ddmax is not None and ddmax > 0:
+                while True:
+                    mask = ddcomponents > ddmax
+                    if np.sum(mask) == 0:
+                        break
+                    ddcomponents[mask] -= 2 * ddmax
+                while True:
+                    mask = ddcomponents < -ddmax
+                    if np.sum(mask) == 0:
+                        break
+                    ddcomponents[mask] += 2 * ddmax
+
+            # Arrows have magnitude of ddcomponent
+            arrowlengths = arrowuvectors * ddcomponents[:,np.newaxis]
+        
+        # Build arrows for vector components
+        else:
+            component = T.dot(component)
+            ddcomponents = ddvectors.dot(component)
+
+            # Normalize ddcomponents to be between +-ddmax
+            if ddmax is not None and ddmax > 0:
+                while True:
+                    mask = ddcomponents > ddmax
+                    if np.sum(mask) == 0:
+                        break
+                    ddcomponents[mask] -= 2 * ddmax
+                while True:
+                    mask = ddcomponents < -ddmax
+                    if np.sum(mask) == 0:
+                        break
+                    ddcomponents[mask] += 2 * ddmax
+
+            # Arrows have magnitude of ddcomponent and direction of uvectors
+            arrowlengths = arrowuvectors * ddcomponents[:,np.newaxis]
+        
+        return arrowlengths, arrowcenters
+
+    def plot_with_nye(self,
+                      component: Union[str, npt.ArrayLike],
+                      ddmax: Optional[float],
+                      strain: Strain,
+                      plotxaxis: Union[str, npt.ArrayLike] = 'x',
+                      plotyaxis: Union[str, npt.ArrayLike] = 'y',
+                      xlim: Optional[tuple] = None,
+                      ylim: Optional[tuple] = None,
+                      zlim: Optional[tuple] = None,
+                      vlim: Optional[tuple] = None,
+                      cmap: str = 'bwr',
+                      arrowscale: float = 1,
+                      arrowwidth: float = 0.005,
+                      use0z: bool = False,
+                      atomcolor: Union[str, list, None] = None,
+                      atomcmap: Union[str, list, None] = None,
+                      atomsize: float = 0.5,
+                      figsize: int = 10,
+                      xbins: int = 200,
+                      ybins: int = 200,
+                      colorbar: bool = True,
+                      fill_value: float = np.nan,
+                      matplotlib_axes: Optional[plt.axes] = None,
+                      ) -> Tuple[float, plt.figure]:
+
+        """
+        Utility function for simple combined dd-Nye plots.  Note that this
+        method is currently limited to components and plot axis values of
+        'x', 'y', and 'z'.  This could be generalized in the future, if 
+        there is interest...
+
+        Parameters
+        ----------
+        component : str or array-like object
+            Indicates the component(s) of the differential displacement to plot.
+            Values of 'x', 'y', or 'z' will plot the component along that
+            Cartesian direction.  A value of 'projection' will plot the
+            differential displacement vectors as projected onto the plotting
+            plane, thereby showing the two components perpendicular to the line
+            direction.  If a 3D vector is given, then the component parallel to
+            that direction will be used.
+        ddmax : float or None
+            The maximum differential displacement value allowed. Values will be
+            kept between +-ddmax by wrapping values with larger absolute values
+            around by adding/subtracting 2*ddmax. Typically, this is set to be
+            |b|/2, but can be defect-specific. For instance, fcc a/2<110>
+            dislocations and basal hcp dislocations are typically plotted with
+            ddmax=|b|/4.  If set to None, then no wrapping is done.
+        strain : atomman.defect.Strain
+            A strain object computed for the system in question.  This will be used
+            to compute the Nye tensor values that are included in the plot.
+        plotxaxis : str or array-like object, optional
+            Indicates the Cartesian direction associated with the system's atomic
+            coordinates to align with the plotting x-axis.  Values are either 3D
+            unit vectors, or strings 'x', 'y', or 'z' for the Cartesian axes
+            directions.  plotxaxis and plotyaxis must be orthogonal.  Default value
+            is 'x' = [1, 0, 0].
+        plotyaxis : str or array-like object, optional
+            Indicates the Cartesian direction associated with the system's atomic
+            coordinates to align with the plotting y-axis.  Values are either 3D
+            unit vectors, or strings 'x', 'y', or 'z' for the Cartesian axes
+            directions.  plotxaxis and plotyaxis must be orthogonal.  Default value
+            is 'y' = [0, 1, 0].
+        xlim : tuple, optional
+            The minimum and maximum coordinates along the plotting x-axis to
+            include in the fit.  Values are taken in the specified length_unit.
+            If not given, then the limits are set based on min and max atomic
+            coordinates along the plotting axis.
+        ylim : tuple, optional
+            The minimum and maximum coordinates along the plotting y-axis to
+            include in the fit.  Values are taken in the specified length_unit.
+            If not given, then the limits are set based on min and max atomic
+            coordinates along the plotting axis.
+        zlim : tuple, optional
+            The minimum and maximum coordinates normal to the plotting axes
+            (i.e. plotxaxis X plotyaxis) to include in the fit.  Values are taken
+            in the specified length_unit.  The optimum zlim should encompass only
+            a single periodic slice.  If not given, then the limits are set
+            based on min and max atomic coordinates along the axis.
+        vlim : tuple, optional
+            Range limits for the Nye tensor contour plot.  If not given, will be
+            determined by the range of the Nye tensor component values.
+        cmap : str, optional
+            The matplotlib colormap to use for the Nye tensor contour plot.
+            Default value is 'bwr'.
+        arrowscale : float, optional
+            Scaling factor for the magnitude of the differential displacement
+            arrows.  Default value is 1: no scaling, vectors are in units of length.
+            For major components, this is often set such that the max differential
+            displacement component after wrapping (see ddmax) is scaled to the
+            distance between the atom pairs in the plot.  For minor components, this
+            is often set to a large value simply to make the components visible.
+        arrowwidth : float, optional
+            Scaling factor to use for the width of the plotted arrows. Default value is
+            0.005 = 1/200.
+        use0z : bool, optional
+            If False (default), the z coordinates from the reference system will be
+            used for zlim and atomcmap colors. If True, the z coordinates will be
+            used from system0 even if system1 is the reference system.
+        atomcolor : str or list, optional
+            Matplotlib color name(s) to use to display the atoms.  If str, that
+            color will be assigned to all atypes.  If list, must give a color value
+            or None for each atype.  Default value (None) will use cmap instead.
+            Note: atomcolor and atomcmap can be used together as long as exactly
+            one color or cmap is given for each unique atype.
+        atomcmap : str or list, optional
+            Matplotlib colormap name(s) to use to display the atoms.  Atoms will
+            be colored based on their initial positions and scaled using zlim. If
+            str, that cmap will be assigned to all atypes.  If list, must give a 
+            cmap value or None for each atype.  Default value (None) will use 'hsv'
+            cmap.  Note: atomcolor and atomcmap can be used together as long as
+            exactly one color or cmap is given for each unique atype.
+        atomsize : float, optional
+            The circle radius size to use for the plotted atom positions in units of
+            length.  Default value is 0.5.
+        figsize : float or tuple, optional
+            Specifies the size of the figure to create in inches.  If a single value
+            is given, it will be used for the figure's width, and the height will be
+            scaled based on the xlim and ylim values.  Alternatively, both the width
+            and height can be set by passing a tuple of two values, but the plot will
+            not be guaranteed to be "regular" with respect to length dimensions.
+        xbins : int, optional
+            Specifies the number of interpolation bins to use along the plotting 
+            x-axis.  Default value is 200.
+        ybins : int, optional
+            Specifies the number of interpolation bins to use along the plotting
+            y-axis.  Default value is 200.
+        colorbar: bool, optional
+            If True (default) a colorbar will be added to the plot.
+        fill_value: float, optional
+            Value used to fill in for grid points failed to interpolate in the fit.
+            If not given, then the default is np.nan, which may cause an error in
+            plotting for too narrow xlim and ylim settings.
+        matplotlib_axes : matplotlib.Axes.axes, optional
+            An existing matplotlib axes object. If given, the differential displacement
+            plot will be added to the specified axes of an existing figure.  This
+            allows for subplots to be constructed.  Note that figsize will be ignored
+            as the figure would have to be created beforehand and no automatic
+            optimum scaling of the figure's dimensions will occur.
+
+        Returns
+        -------
+        float
+            The integer sum of the Nye tensor over the plotted area.
+        matplotlib.Figure
+            The generated figure.
+
+        """
+        # Identify Nye tensor components based on component and plot axes
+        try: 
+            component_index = ['x', 'y', 'z'].index(component)
+        except:
+            raise ValueError('component is currently limited to values of "x", "y" or "z"') 
+        try:
+            x_index = ['x', 'y', 'z'].index(plotxaxis)
+        except:
+            raise ValueError('plotxaxis is currently limited to values of "x", "y" or "z"')
+        try:
+            y_index = ['x', 'y', 'z'].index(plotyaxis)
+        except:
+            raise ValueError('plotyaxis is currently limited to values of "x", "y" or "z"')
+        line_index = 3 - (x_index + y_index)
+        prop_index = [line_index, component_index] 
+        
+        # Generate dd plot
+        if matplotlib_axes is None:
+            fig = self.plot(component, ddmax, plotxaxis=plotxaxis, plotyaxis=plotyaxis,
+                            xlim=xlim, ylim=ylim, zlim=zlim, arrowscale=arrowscale,
+                            arrowwidth=arrowwidth, use0z=use0z, atomcolor=atomcolor,
+                            atomcmap=atomcmap, atomsize=atomsize, figsize=figsize)
+            matplotlib_axes = fig.axes[0]
+        else:
+            self.plot(component, ddmax, plotxaxis=plotxaxis, plotyaxis=plotyaxis,
+                      xlim=xlim, ylim=ylim, zlim=zlim, arrowscale=arrowscale,
+                      arrowwidth=arrowwidth, use0z=use0z, atomcolor=atomcolor,
+                      atomcmap=atomcmap, atomsize=atomsize, figsize=figsize,
+                      matplotlib_axes=matplotlib_axes)
+            fig = None
+
+        # Add Nye tensor surface plot
+        intsum = interpolate_contour(self.system1, 'nye', prop_index=prop_index, prop=strain.nye,
+                            plotxaxis=plotxaxis, plotyaxis=plotyaxis,
+                            xlim=xlim, ylim=ylim, zlim=zlim, vlim=vlim, cmap=cmap,
+                            xbins=xbins, ybins=ybins, fill_value=fill_value, 
+                            matplotlib_axes=matplotlib_axes,
+                            dots=False, colorbar=colorbar, title=False)[0]
+        
+        if fig is None:
+            return intsum
+        else:
+            return intsum, fig

atomman/source/atomman/defect/Dislocation/__init__.py

@@ -0,0 +1,535 @@
+# coding: utf-8
+# Standard Python libraries
+import io
+from typing import Optional, Union
+from itertools import product
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+from yabadaba.record import Record
+
+# atomman imports
+from .. import solve_volterra_dislocation, VolterraDislocation
+from ... import System, ElasticConstants, load
+from ...tools import miller, vect_angle, boolean
+from ...library import load_record, Database
+
+class Dislocation():
+
+    from ._monopole import monopole, cylinder_boundary, box_boundary
+    from ._periodicarray import (periodicarray, array_boundary,
+                                 build_disl_array)
+    from ._dipole import dipole, dipole_displacement
+
+    def __init__(self,
+                 ucell: System,
+                 C: ElasticConstants,
+                 burgers: npt.ArrayLike,
+                 ξ_uvw: npt.ArrayLike,
+                 slip_hkl: npt.ArrayLike,
+                 conventional_setting: str = 'p',
+                 ucell_setting: Optional[str] = None,
+                 m: Union[str, npt.ArrayLike] = 'y',
+                 n: Union[str, npt.ArrayLike] = 'z',
+                 shift: Optional[npt.ArrayLike] = None,
+                 shiftindex: Optional[int] = None,
+                 shiftscale: bool = False,
+                 tol: float = 1e-8):
+        """
+        Class initializer.  Solves the dislocation solution and rotates the
+        given unit cell to the proper orientation.
+
+        Parameters
+        ----------
+        ucell : atomman.System
+            The unit cell to use as the seed for generating the dislocation
+            monopole system.
+        C : atomman.ElasticConstants
+            The elastic constants associated with the bulk crystal structure
+            for ucell.
+        burgers : array-like object
+            The dislocation's Burgers vector given as a Miller or
+            Miller-Bravais vector relative to ucell.
+        ξ_uvw : array-like object
+            The dislocation's line direction given as a Miller or
+            Miller-Bravais vector relative to ucell.
+        slip_hkl : array-like object
+            The dislocation's slip plane given as a Miller or Miller-Bravais
+            plane relative to ucell.
+        conventional_setting : str, optional
+            Indicates the space lattice setting of the given unit cell, i.e.
+            'p' for primitive, 'i' for body-centered, 'f' for face-centered,
+            'a', 'b', or 'c' for side-centered and 't1', or 't2' for trigonal
+            in a hexagonal setting.  Setting this with the appropriate
+            conventional unit cell allows for identifying lattice vectors that
+            are not integers with respect to the conventional unit cell.  This
+            also creates the rotated cell from a compatible primitive cell,
+            thereby the final dislocation configurations can be smaller than
+            possible solely from the conventional unit cell.
+        m : str or array-like object, optional
+            The Cartesian axis to align with the dislocation solution's m-axis,
+            i.e. the in-plane direction perpendicular to the dislocation line.
+            Can be specified as a 3D vector or str values 'x', 'y', or 'z'.  
+            Default value is 'y' as this corresponds to the optimum alignment
+            for LAMMPS systems.
+        n : str or array-like object, optional
+            The Cartesian axis to align with the dislocation solution's n-axis,
+            i.e. the slip plane normal.  Can be specified as a 3D vector or str
+            values 'x', 'y', or 'z'.  Default value is 'z' as this corresponds
+            to the optimum alignment for LAMMPS systems.
+        shift : array-like object, optional
+            A rigid body shift to apply to the rotated cell prior to inserting
+            the dislocation.  Should be selected such that the ideal slip plane
+            does not correspond to any atomic planes.  Is taken as absolute if
+            shiftscale is False, or relative to the rotated cell's box vectors
+            if shiftscale is True.  Cannot be given with shiftindex.  If
+            neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftindex : float, optional
+            The index of the identified optimum shifts based on the rotated
+            cell to use.  Different values allow for the selection of different
+            atomic planes neighboring the slip plane.  Note that shiftindex
+            values only apply shifts normal to the slip plane; best shifts for
+            non-planar dislocations (like bcc screw) may also need a shift in
+            the slip plane.  Cannot be given with shiftindex.  If neither shift
+            nor shiftindex is given then shiftindex = 0 is used.
+        shiftscale : bool, optional
+            If False (default), a given shift value will be taken as absolute
+            Cartesian.  If True, a given shift will be taken relative to the
+            rotated cell's box vectors.
+        tol : float
+            A cutoff tolerance used with obtaining the dislocation solution.
+            Only needs to be changed if there are issues with obtaining a
+            solution.
+        """
+        
+        # Generate the dislocation solution
+        self.__dislsol = solve_volterra_dislocation(C, burgers, ξ_uvw=ξ_uvw,
+                                                    slip_hkl=slip_hkl, m=m, n=n,
+                                                    cart_axes=True,
+                                                    box=ucell.box, tol=tol)
+        self.__transform = self.dislsol.transform
+
+        if ucell_setting is not None:
+            raise TypeError('ucell_setting has been renamed conventional_setting for consistency')
+
+        # Build rcell and set orientation parameters
+        self.__set_cells(ucell, ξ_uvw, setting=conventional_setting, maxindex=5, tol=tol)
+
+        # Set shift value based on shift parameters
+        self.__identify_shifts(tol)
+        self.set_shift(shift, shiftindex, shiftscale)
+
+        # Set base_system and disl_system to None
+        self.__base_system = None
+        self.__disl_system = None
+
+    @classmethod
+    def fromrecord(cls,
+                   record: Union[str, io.IOBase, DM, Record],
+                   ucell: System,
+                   C: ElasticConstants,
+                   tol: float = 1e-8):
+        """
+        Initializes a Dislocation object based on pre-defined dislocation
+        parameters from a reference record.
+
+        Parameters
+        ----------
+        record : atomman.library.record.Dislocation, str, file-like object or DataModelDict
+            A Dislocation record object or the model contents for one.
+        ucell : atomman.System
+            The unit cell to use as the seed for generating the dislocation
+            monopole system.
+        C : atomman.ElasticConstants
+            The elastic constants associated with the bulk crystal structure
+            for ucell.
+        model : str, file-like object or DataModelDict
+            The reference record containing dislocation parameters to use.
+        tol : float
+            A cutoff tolerance used with obtaining the dislocation solution.
+            Only needs to be changed if there are issues with obtaining a
+            solution.
+        """
+        # Create record object if needed
+        if not isinstance(record, Record):
+            record = load_record('dislocation', model=record)
+
+        # Extract the dislocation parameters
+        slip_hkl = miller.fromstring(record.parameters['slip_hkl'])
+        ξ_uvw = miller.fromstring(record.parameters['ξ_uvw'])
+        burgers = miller.fromstring(record.parameters['burgers'])
+        m = np.fromstring(record.parameters.get('m', '0 1 0'), sep=' ')
+        n = np.fromstring(record.parameters.get('n', '0 0 1'), sep=' ')
+        conventional_setting = record.parameters.get('conventional_setting', 'p')
+
+        shift = record.parameters.get('shift', None)
+        shiftindex = record.parameters.get('shiftindex', None)
+        shiftscale = boolean(record.parameters.get('shiftscale', False))
+
+        if shift is not None:
+            shift = np.fromstring(shift, sep=' ')
+        elif shiftindex is not None:
+            shiftindex = int(shiftindex)
+
+        return cls(ucell, C, burgers, ξ_uvw, slip_hkl, m=m, n=n, shift=shift,
+                   shiftindex=shiftindex, shiftscale=shiftscale, 
+                   conventional_setting=conventional_setting, tol=tol)
+
+    @classmethod
+    def fromdatabase(cls,
+                     name: Optional[str] = None,
+                     ucell: Optional[System] = None,
+                     C: Optional[ElasticConstants] = None,
+                     database: Optional[Database] = None,
+                     prompt: bool = True,
+                     tol: float = 1e-8,
+                     **kwargs):
+        """
+        Construct a Dislocation object based on record(s) retrieved from the
+        reference database.
+
+        Parameters
+        ----------
+        name : str or None, optional
+            The name of the dislocation record to retrieve from the database.
+            Alternatively, you can use any other query keyword arguments supported
+            by the dislocation record style (see **kwargs below for more info).
+        ucell : atomman.System or None, optional
+            The unit cell to use in generating the system.  If None (default), then
+            the crystal_prototype record that matches the defect's family setting
+            will be loaded from the database.  Note that if None then the
+            crystal-specific info (lattice constants and symbols) should be given
+            here as kwargs (see below).
+        C : atomman.ElasticConstants, optional
+            The elastic constants associated with the bulk crystal structure
+            for ucell. Required, but future versions may fetch from the database.
+        database : atomman.library.Database or None, optional
+            A Database object to use to fetch the records.  If None (default), then
+            a new Database instance will be created.
+        prompt : bool
+            If prompt=True (default) then a screen input will ask for a selection
+            if multiple matching dislocation (or crystal_prototype) records are
+            found.  If prompt=False, then an error will be thrown if multiple
+            matches are found.
+        maxindex : int, optional
+            Max uvw index value to use in identifying the best uvw set for the
+            out-of-plane vector.  If not given, will use the largest absolute
+            index between the given hkl and the initial in-plane vector guesses.
+        tol : float, optional
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        **kwargs : any
+            The recognized kwargs include the query keywords for free_surface
+            records (key, id, character, family), and the
+            crystal-specific parameters recognized by the prototype load style
+            (a, b, c, alpha, beta, gamma, symbols).  The non-trivial
+            crystal-specific parameters should be for the crystal if ucell is
+            not given above as the crystal prototype lacks this information.
+        """
+        # Initialize a database if needed
+        if database is None:
+            database = Database()
+
+        # Extract ucell parameters from kwargs
+        prototype_kwargs = {}
+        prototype_kwargs_names = ['a', 'b', 'c', 'alpha', 'beta', 'gamma', 'symbols']
+        for prototype_kwargs_name in prototype_kwargs_names:
+            if prototype_kwargs_name in kwargs:
+                prototype_kwargs[prototype_kwargs_name] = kwargs.pop(prototype_kwargs_name)
+
+        # Fetch matching defect record
+        record = database.get_record('dislocation', name=name, prompt=prompt, **kwargs)
+
+        # Fetch crystal prototype unit cell if needed
+        if ucell is None:
+            ucell = load('prototype', name=record.family, **prototype_kwargs)
+        else:
+            if len(prototype_kwargs) > 0:
+                raise ValueError('crystal-specific kwargs cannot be given with ucell')
+
+        return cls.fromrecord(record=record, ucell=ucell, C=C, tol=tol)
+
+    @property
+    def dislsol(self) -> VolterraDislocation:
+        """atomman.defect.VolterraDislocation: The elastic dislocation solution"""
+        return self.__dislsol
+
+    @property
+    def uvws(self) -> np.ndarray:
+        """numpy.NDArray: The 3x3 array of uvw Miller vectors that correspond
+        to the rcell orientation.
+        """
+        return self.__uvws
+
+    @property
+    def uvws_prim(self) -> np.ndarray:
+        """numpy.NDArray: The 3x3 array of uvw Miller vectors used to rotate
+        ucell_prim to rcell.
+        """
+        return self.__uvws_prim
+
+    @property
+    def transform(self) -> np.ndarray:
+        """numpy.NDArray: The 3x3 Cartesian transformation matrix associated
+        with rotating from ucell to rcell.
+        """
+        return self.__transform
+
+    @property
+    def ucell(self) -> System:
+        """atomman.System: The reference conventional unit cell for the
+        dislocation system.
+        """
+        return self.__ucell
+
+    @property
+    def ucell_prim(self) -> System:
+        """atomman.System: The primitive unit cell of ucell used as the basis
+        for constructing rcell.
+        """
+        return self.__ucell_prim
+
+    @property
+    def rcell(self) -> System:
+        """atomman.System: The rotated cell that coincides with the dislocation
+        solution orientation.
+        """
+        return self.__rcell
+
+    @property
+    def lineindex(self) -> int:
+        """int: The index of the box vector that coincides with the dislocation
+        line: 0=a, 1=b, 2=c.
+        """
+        return self.__lineindex
+
+    @property
+    def cutindex(self) -> int:
+        """int: The index of the box vector that is not within the slip plane:
+        0=a, 1=b, 2=c.
+        """
+        return self.__cutindex
+
+    @property
+    def motionindex(self) -> int:
+        """int: The index of the box vector that is not the line or cut
+        directions: 0=a, 1=b, 2=c.
+        """
+        return self.__motionindex
+
+    @property
+    def shifts(self) -> list:
+        """list: All identified shifts that will place the slip plane halfway
+        between atomic planes.
+        """
+        return self.__shifts
+
+    @property
+    def shift(self) -> np.ndarray:
+        """numpy.NDArray: The particular shift value that will be or was used
+        to construct the dislocation system.
+        """
+        return self.__shift
+
+    @property
+    def base_system(self) -> System:
+        """atomman.System: The "perfect crystal" reference system associated
+        with the dislocation system.
+        """
+        if self.__base_system is not None:
+            return self.__base_system
+        else:
+            raise ValueError(
+                'base_system not built yet: must call monopole() or periodicarray() first'
+            )
+
+    @property
+    def disl_system(self) -> System:
+        """atomman.System: The generated dislocation system."""
+        if self.__disl_system is not None:
+            return self.__disl_system
+        else:
+            raise ValueError(
+                'disl_system not built yet: must call monopole() or periodicarray() first'
+            )
+
+    def __set_cells(self, ucell, ξ_uvw, setting, maxindex=5, tol=1e-8):
+
+        # Extract dislsol
+        dislsol = self.dislsol
+
+        # Get primitive cell and associated transformation matrix
+        ucell_prim, c2p_transform = ucell.dump('conventional_to_primitive', setting=setting,
+                                                return_transform=True, atol=tol)
+
+        # Convert ξ_uvw to the primitive cell
+        ξ_uvw = np.asarray(ξ_uvw, dtype=float)
+        if ξ_uvw.shape[-1] == 4:
+            ξ_uvw = miller.vector4to3(ξ_uvw)
+            hexindices = True
+        else:
+            hexindices = False
+        ξ_uvw_p = miller.vector_conventional_to_primitive(ξ_uvw, setting=setting)
+
+        # Get Cartesian m, n axes relative to ucell_prim
+        m_cart = c2p_transform.dot(dislsol.m.dot(dislsol.transform))
+        n_cart = c2p_transform.dot(dislsol.n.dot(dislsol.transform))
+
+        # Generate an array of all int uvws with abs(u, v, w) <= maxindex
+        alluvws = np.array([p for p in product(range(-maxindex, maxindex+1), repeat=3)])
+        alluvws = alluvws[np.abs(alluvws).sum(axis=1) != 0]  # Remove [0, 0, 0]
+
+        # Convert alluvws to Cartesian wrt the primitive ucell box
+        alluvws_cart = ucell_prim.box.vector_crystal_to_cartesian(alluvws)
+
+        # Compute the angles between alluvws and the m, n axes
+        m_angle = vect_angle(alluvws_cart, m_cart)
+        n_angle = vect_angle(alluvws_cart, n_cart)
+
+        # Find in-plane uvw closest to m
+        inplane_uvws = alluvws[np.isclose(n_angle, 90.0)]
+        inplane_m_angle = m_angle[np.isclose(n_angle, 90.0)]
+        m_uvw = inplane_uvws[np.isclose(inplane_m_angle, inplane_m_angle.min())]
+        if len(m_uvw) > 0:
+            m_uvw = m_uvw[0] / np.gcd.reduce(np.asarray(m_uvw[0], dtype=int))
+        else:
+            raise ValueError('Failed to find vector near edge component direction')
+
+        # Find uvw closest to n
+        n_uvw = alluvws[np.isclose(n_angle, n_angle.min())]
+        if len(n_uvw) > 0:
+            n_uvw = n_uvw[0] / np.gcd.reduce(np.asarray(n_uvw[0], dtype=int))
+        else:
+            raise ValueError('Failed to find vector near slip plane normal')
+
+        # Identify lineindex and cutindex
+        indices = np.array([0, 1, 2])
+        cutindex = indices[np.isclose(np.abs(dislsol.n), 1.0)][0]
+        lineindex = indices[np.isclose(np.abs(dislsol.ξ), 1.0)][0]
+        if cutindex == lineindex:
+            raise RuntimeError('Encountered cutindex == lineindex: should not be possible!')
+
+        # Orient the uvw sets based on cutboxvector and ξboxvector
+        if cutindex == 2:
+            if lineindex == 0:
+                uvws = np.array([ξ_uvw_p, m_uvw, n_uvw])
+            else:
+                uvws = np.array([-m_uvw, ξ_uvw_p, n_uvw])
+
+        elif cutindex == 1:
+            if lineindex == 2:
+                uvws = np.array([m_uvw, n_uvw, ξ_uvw_p])
+            else:
+                uvws = np.array([ξ_uvw_p, n_uvw, -m_uvw])
+
+        elif cutindex == 0:
+            if lineindex == 1:
+                uvws = np.array([n_uvw, ξ_uvw_p, m_uvw])
+            else:
+                uvws = np.array([n_uvw, -m_uvw, ξ_uvw_p])
+
+        # Generate rcell
+        rcell = ucell_prim.rotate(uvws)
+
+        # Save cells and orientation parameters as object attributes
+        self.__ucell = ucell
+        self.__ucell_prim = ucell_prim
+        self.__rcell = rcell
+
+        uvws_conv = miller.vector_primitive_to_conventional(uvws, setting=setting)
+        if hexindices:
+            self.__uvws = miller.vector3to4(uvws_conv)
+        else:
+            self.__uvws = uvws_conv
+        self.__uvws_prim = uvws
+        self.__lineindex = lineindex
+        self.__cutindex = cutindex
+        self.__motionindex = 3 - (lineindex + cutindex)
+
+    def __identify_shifts(self, tol):
+
+        # Define out of plane unit vector
+        ovect = self.dislsol.n
+
+        # Get out of plane width
+        rcellwidth = self.rcell.box.vects[self.cutindex, self.cutindex]
+
+        # Get the unique coordinates normal to the plane
+        pos = self.rcell.atoms.pos
+        numdec = - int(np.floor(np.log10(tol)))
+        coords = np.unique(pos[:, self.cutindex].round(numdec))
+
+        # Add periodic replica if missing
+        if not np.isclose(coords[-1] - coords[0], rcellwidth, rtol=0.0, atol=tol):
+            coords = np.append(coords, coords[0] + rcellwidth)
+
+        # Compute the shifts
+        relshifts = rcellwidth - (coords[1:] + coords[:-1]) / 2
+        relshifts[relshifts > rcellwidth] -= rcellwidth
+        relshifts[relshifts < 0.0] += rcellwidth
+        self.__shifts = np.outer(np.sort(relshifts), ovect)
+
+    def set_shift(self,
+                  shift: Optional[npt.ArrayLike] = None,
+                  shiftindex: Optional[int] = None,
+                  shiftscale: bool = False):
+        """
+        Directly set the shift value based on shiftindex, or shift and shiftscale.
+        NOTE that the shift value can alternatively be set during class initialization
+        or when surface() is called.
+
+        Parameters
+        ----------
+        shift : array-like object, optional
+            Applies a shift to all atoms. Different values allow for free surfaces with
+            different termination planes to be selected.  shift is taken as absolute
+            if shiftscale is False, or relative to the rotated cell's box vectors
+            if shiftscale is True.  Cannot be given with shiftindex.  If
+            neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftindex : float, optional
+            The index of the identified shifts based on the rotated
+            cell to use.  Different values allow for the selection of different
+            atomic planes neighboring the slip plane.  Cannot be given with shift.
+            If neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftscale : bool, optional
+            If False (default), a given shift value will be taken as absolute
+            Cartesian.  If True, a given shift will be taken relative to the
+            rotated cell's box vectors.
+        """
+        # Handle shift parameters
+        if shift is not None:
+            if shiftindex is not None:
+                raise ValueError('shift and shiftindex cannot both be given')
+            if shiftscale is True:
+                self.__shift = miller.vector_crystal_to_cartesian(shift, self.rcell.box)
+            else:
+                self.__shift = np.asarray(shift)
+                assert self.__shift.shape == (3,)
+
+        elif shiftindex is not None:
+            self.__shift = self.shifts[shiftindex]
+
+        else:
+            self.__shift = self.shifts[0]
+
+    def set_systems(self,
+                    base_system: System,
+                    disl_system: System):
+        """
+        Used by the configuration generators to set base and dislocation systems
+        as class attributes.
+
+        Parameters
+        ----------
+        base_system : atomman.System
+            The base reference system.
+        disl_system : atomman.System
+            The dislocation system.
+        """
+        self.__base_system = base_system
+        self.__disl_system = disl_system

atomman/source/atomman/defect/Dislocation/_dipole.py

@@ -0,0 +1,300 @@
+# coding: utf-8
+from typing import Optional, Tuple, Union
+from copy import deepcopy
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# Local imports
+from ... import System
+from . import VolterraDislocation
+
+@staticmethod
+def dipole_displacement(dislsol: VolterraDislocation,
+                        pos: npt.ArrayLike,
+                        x1: Union[float, npt.ArrayLike],
+                        x2: Union[float, npt.ArrayLike],
+                        mvect: npt.ArrayLike,
+                        nvect: npt.ArrayLike,
+                        N: int = 5) -> np.ndarray:
+    """
+    Uses the method of Cai, Bulatov, Chang, Li & Yip, Phil Mag 2003, 83(5), 539-567
+    https://doi.org/10.1080/0141861021000051109 to compute the displacement associated
+    with a dislocation dipole in a periodic lattice.
+
+    Parameters
+    ----------
+    dislsol : atomman.defect.VolterraDislocation
+        A Volterra dislocation solution object. This provides the dislocation
+        orientation (m, n vectors) and the displacement solutions for the two
+        individual dislocations of opposite Burgers vectors.
+    pos : array-like object
+        The coordinates to evaluate the displacement at.
+    x1 : float or array-like object
+        The coordinate(s) of the first dislocation.  If a float is given, it will be
+        multiplied by the dislocation solution's m vector.
+    x2 : float or array-like object
+        The coordinate(s) of the second dislocation.  If a float is given, it will be
+        multiplied by the dislocation solution's m vector.
+    mvect : array-like object
+        One of the two 2D cell vectors.  This should be parallel to the dislocation
+        solution's m vector and a whole periodic lattice vector.
+    nvect : array-like object
+        One of the two 2D cell vectors.  This should be a whole lattice vector with
+        major component along the dislocation solution's n vector. It does not need
+        to be parallel to n and can have components in either of the two coordinate
+        directions.
+    N : int, optional
+        Indicates how many image cells are used. A rectangular grid of images is used
+        meaning that there will be NxN total cells evaluated, of which NxN-1 will be
+        image cells.  Default value is 5.
+
+    Returns
+    -------
+    displacement : numpy.NDArray
+        The associated displacement field evaluated at pos for the dipole configuration.
+    """
+
+    # Extract the dislocation solution m,n axes
+    m = dislsol.m
+    n = dislsol.n
+
+    # Manage input parameters
+    pos = np.asarray(pos)
+    mvect = np.asarray(mvect)
+    nvect = np.asarray(nvect)
+    if isinstance(x1, (float, int)):
+        x1 = x1 * m
+    else:
+        x1 = np.asarray(x1)
+    if isinstance(x2, (float, int)):
+        x2 = x2 * m
+    else:
+        x2 = np.asarray(x2)
+
+    # Define the non-periodic component of the displacement
+    def nonperiodic(pos):
+        """
+        The dipole displacement field in an infinite medium, i.e. no periodic
+        replicas only the two dislocations themselves.
+        """
+        disp1 = dislsol.displacement(pos - x1)
+        disp2 = dislsol.displacement(pos - x2)
+
+        return disp1 - disp2
+
+    # Define the periodic component of the displacement
+    def periodic(pos):
+        """
+        The dipole displacement field including periodic replicas from i,j = -N to N
+        in both directions normal to the dislocation line.  NOTE that this includes the
+        non-periodic component i=j=0. 
+        """
+        disp = np.zeros_like(pos)
+        for i in range(-N, N+1):
+            for j in range(-N, N+1):
+                shifted_pos = pos + i * mvect + j * nvect
+                disp += nonperiodic(shifted_pos)
+
+        return disp
+
+    # Get m, n components of mvect and nvect
+    mn = np.array([mvect, nvect]).dot(np.array([m, n]).T)
+
+    # Get reciprocal of mn
+    reciprocal_mn = np.linalg.inv(mn).T
+
+    # Compute the displacement values at the four corners of the 2D [mvect, nvect] cell
+    corners = np.array([
+        -0.5 * mvect - 0.5 * nvect, # bottom left corner, blc
+         0.5 * mvect - 0.5 * nvect, # blc + mvect
+        -0.5 * mvect + 0.5 * nvect, # blc + nvect
+         0.5 * mvect + 0.5 * nvect]) # blc + mvect + nvect
+    disp_corners = periodic(corners)
+
+    # Find total changes in displacement along mvect and nvect
+    delta_disp = np.array([disp_corners[1] - disp_corners[0], disp_corners[2] - disp_corners[0]])
+
+    # Define the correction component of the displacement
+    def correction(pos):
+        """
+        This computes the linear displacement correction to apply to the system
+        to ensure that it is compatible across the periodic boundaries
+        """
+        # Transform pos to be relative to mn and multiply by delta disp
+        pos_mn = np.vstack([pos.dot(m), pos.dot(n)]).T
+        relpos_mn = np.inner(pos_mn, reciprocal_mn)
+        disp = relpos_mn.dot(delta_disp)
+
+        return disp
+
+    # Verify the correction against the corners
+    correction_test = disp_corners - correction(corners)
+    assert(np.allclose(correction_test[0], correction_test[1]))
+    assert(np.allclose(correction_test[0], correction_test[2]))
+    assert(np.allclose(correction_test[0], correction_test[3]))
+
+    # Compute the displacements for pos
+    disp = periodic(pos) - correction(pos)
+
+    return disp
+
+def dipole(self,
+           sizemults: Tuple,
+           boxtilt: bool = True,
+           numreplicas: int = 5,
+           shift: Optional[npt.ArrayLike] = None,
+           shiftindex: Optional[int] = None,
+           shiftscale: bool = False,
+           center: Optional[npt.ArrayLike] = None,
+           centerscale: bool = False,
+           return_base_system: bool = False
+           ) -> Union[System, Tuple[System, System]]:
+    """
+    Constructs a dislocation dipole configuration as described by Li, Wang,
+    Chang, Cai, Bulatov, Ho, Yip, Phys Rev B 70(10) (2004) 104113 
+    https://doi.org/10.1103/Physrevb.70.104113.  Two parallel dislocations with
+    opposite Burgers vectors will be inserted into the system using a Volterra
+    solution.  The resulting configuration is periodic in all three directions
+    and constitutes a regularly-spaced 2D grid of parallel dislocations.  A
+    shear strain is also applied to the system of 1/2 the Burgers vector to
+    counteract the elastic strain of the dislocations and ensure stability.
+
+    Parameters
+    ----------
+    sizemults : tuple
+        The three size multipliers to use when generating the system.  Values
+        should be positive integers if boxtilt is False.  When boxtilt is True,
+        the multipliers are limited to values that result in full lattice
+        vectors once the tilt is added.  Depending on the system, fractional
+        values may be possible, or some integer values not allowed.
+    boxtilt : bool, optional
+        If True (default) then a tilt will be applied to the system such that
+        the resulting periodic configuration will be consistent with a
+        "quadripole" representation in which each dislocation will be
+        surrounded by dislocations of the opposite sign in both the m- and n-
+        directions.  This is achieved by adding half of the box vector
+        most aligned with the m-axis to the box vector most aligned with the
+        n-axis.  A value of False will not tilt the system, so only the
+        sizemults will be applied to the rotated cell. The non-tilted system
+        will have dislocations of the same sign aligned along the n-axis.
+    numreplicas : int, optional
+        Indicates how many image cells are used for computing the displacement
+        field of the dipole. A rectangular grid of images is used
+        meaning that there will be NxN total cells evaluated, of which NxN-1
+        will be image cells.  Default value is 5.
+    shift : array-like object, optional
+        A rigid body shift to apply to the rotated cell prior to inserting
+        the dislocation.  Should be selected such that the ideal slip plane
+        does not correspond to any atomic planes.  Is taken as absolute if
+        shiftscale is False, or relative to the rotated cell's box vectors
+        if shiftscale is True.  Cannot be given with shiftindex.  If
+        neither shift nor shiftindex is given will use the shift set during
+        class initialization.
+    shiftindex : float, optional
+        The index of the identified optimum shifts based on the rotated
+        cell to use.  Different values allow for the selection of different
+        atomic planes neighboring the slip plane.  Note that shiftindex
+        values only apply shifts normal to the slip plane; best shifts for
+        non-planar dislocations (like bcc screw) may also need a shift in
+        the slip plane.  Cannot be given with shiftindex.  If neither shift
+        nor shiftindex is given then shiftindex = 0 is used then will use
+        the shift set during class initialization.
+    shiftscale : bool, optional
+        If False (default), a given shift value will be taken as absolute
+        Cartesian.  If True, a given shift will be taken relative to the
+        rotated cell's box vectors.
+    center : array-like object or None, optional
+        Indicates where the dislocations are positioned in the configuration
+        relative to the default locations.  For dipole configurations, the
+        default locations are at relative positions of (1/4, 1/2) and 
+        (3/4, 1/2) of the box dimensions of the final configuration that
+        correspond to the dislocation solution's m- and n-axes.
+    centerscale : bool, optional
+        If False (default), a given center value will be taken as absolute
+        Cartesian.  If True, a given center will be taken relative to the
+        rotated cell's box vectors.
+    return_base_system : bool, optional
+        If True then the dislocation-free base system corresponding to the
+        dislocation system will also be returned.  The base system is used
+        as a reference state for most of the dislocation analysis tools.
+
+    Returns
+    -------
+    base_system : atomman.System
+        The base "perfect crystal" reference system associated with the
+        dislocation system. Only returned if return_base_system is True.
+    disl_system : atomman.System
+        The generated dislocation monopole system.
+    """
+    # Extract box vector orientations
+    cutindex = self.cutindex
+    #lineindex = self.lineindex
+    motionindex = self.motionindex
+
+    # Multiply primitive uvws by sizemults to get dipole rotation uvws
+    uvws_dipole = (np.asarray(sizemults) * self.uvws_prim.T).T
+    
+    # Apply boxtilt
+    if boxtilt:
+        uvws_dipole[cutindex] += uvws_dipole[motionindex] / 2
+
+    # Check that the uvws are lattice vectors
+    if not np.allclose(uvws_dipole, np.asarray(np.rint(uvws_dipole), dtype='int64')):
+        raise ValueError(f'sizemults (and boxtilt) did not result in int lattice vectors: {uvws_dipole}')
+
+    # Create base_system
+    base_system = self.ucell_prim.rotate(uvws_dipole)
+
+    # Handle shift parameters
+    if shift is not None or shiftindex is not None:
+        self.set_shift(shift, shiftindex, shiftscale)
+    shift = self.shift
+    
+    # Handle center parameter
+    if center is None:
+        center = np.array([0,0,0])
+    else:
+        center = np.asarray(center)
+    if centerscale:
+        center = self.rcell.box.vector_crystal_to_cartesian(center)
+
+    # Apply the rigid body shift to the atoms
+    base_system.atoms.pos += shift
+
+    # Move the box origin to the center of the system
+    neworigin = - (base_system.box.vects[cutindex] + base_system.box.vects[motionindex]) / 2
+    base_system.box_set(vects=base_system.box.vects, origin=neworigin)
+
+    # Identify x1 and x2 positions
+    m = self.dislsol.m
+    length = base_system.box.vects.dot(m).dot(m)
+    x2 = (length / 4) * m
+    x1 = -x2
+
+    # Shift atoms so that dislocation solution is centered at x1
+    base_system.atoms.pos += x1
+    base_system.wrap()
+
+    # Compute displacement solution
+    mvect = base_system.box.vects[motionindex]
+    nvect = base_system.box.vects[cutindex]
+    disp = self.dipole_displacement(self.dislsol, base_system.atoms.pos - center,
+                                    x1, x2, mvect, nvect, N=numreplicas)
+
+    # Create the dislocation system
+    disl_system = deepcopy(base_system)
+    disl_system.atoms.pos += disp
+
+    # Apply the balancing strain (ONLY FOR SCREW RIGHT NOW!)
+    newvects = disl_system.box.vects
+    newvects[cutindex] -= 0.5 * self.dislsol.burgers
+    disl_system.box_set(vects=newvects, origin=disl_system.box.origin, scale=True)
+
+    self.set_systems(base_system, disl_system)
+
+    if return_base_system:
+        return base_system, disl_system
+    else:
+        return disl_system

atomman/source/atomman/defect/Dislocation/_monopole.py

@@ -0,0 +1,335 @@
+# coding: utf-8
+# Standard Python libraries
+from copy import deepcopy
+from typing import Optional, Tuple, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# atomman imports
+from ... import Box, System
+from ...region import PlaneSet, Cylinder
+
+def box_boundary(self,
+                 box: Box,
+                 width: float) -> PlaneSet:
+    """
+    Constructs a shape associated with the box-style boundary region.  Used
+    by the monopole() generation method.  The returned shape will encompass
+    all atoms except those within width distance of the two non-periodic
+    surfaces.
+
+    Parameters
+    ----------
+    box : atomman.Box
+        The box associated with the full (base) system.
+    width : float
+        The width of the boundary region
+
+    Returns
+    -------
+    atomman.region.PlaneSet
+        The Shape object excluding the boundary region
+    """
+    # Get plane shapes for the two non-periodic directions
+    planes = []
+    for i in range(3):
+        if i == self.lineindex:
+            continue
+        planes.append(box.planes[i])
+        planes.append(box.planes[i+3])
+
+    # Shift plane points by width in the plane normal directions
+    for plane in planes:
+        plane.point -= width * plane.normal
+
+    # Create and return shape
+    return PlaneSet(planes)
+
+def cylinder_boundary(self,
+                      box: Box,
+                      width: float) -> Cylinder:
+    """
+    Constructs a shape associated with the cylinder-style boundary region.
+    Used by the monopole() generation method.  The returned shape will
+    encompass a cylinder of atoms centered around the dislocation line
+    leaving a boundary region that will be at least width wide everywhere.
+
+    Parameters
+    ----------
+    box : atomman.Box
+        The box associated with the full (base) system.
+    width : float
+        The minimum width of the boundary region.
+
+    Returns
+    -------
+    atomman.region.Cylinder
+        The Shape object excluding the boundary region
+    """
+    # Reduce the problem to 2D: solution independent of ξ position
+    mn = np.array([self.dislsol.m, self.dislsol.n])
+    vect1 = mn.dot(box.vects[self.lineindex - 2])
+    vect2 = mn.dot(box.vects[self.lineindex - 1])
+    origin = mn.dot(box.origin)
+
+    # Compute normal vectors to box vectors
+    normal_vect1 = np.array([-vect1[1], vect1[0]])
+    normal_vect2 = np.array([vect2[1], -vect2[0]])
+    normal_vect1 = normal_vect1 / np.linalg.norm(normal_vect1)
+    normal_vect2 = normal_vect2 / np.linalg.norm(normal_vect2)
+
+    def line(p1, p2):
+        """
+        Defines a 2D line as used by the intersection function
+        """
+        A = (p1[1] - p2[1])
+        B = (p2[0] - p1[0])
+        C = (p1[0]*p2[1] - p2[0]*p1[1])
+        return A, B, -C
+
+    def intersection(L1, L2):
+        """
+        Identifies the (x,y) coordinates where two 2D lines intersect
+        """
+        D  = L1[0] * L2[1] - L1[1] * L2[0]
+        Dx = L1[2] * L2[1] - L1[1] * L2[2]
+        Dy = L1[0] * L2[2] - L1[2] * L2[0]
+        if D != 0:
+            x = Dx / D
+            y = Dy / D
+            return x, y
+        else:
+            return False
+
+    # Define normal lines as originating at (0,0)
+    normal_line_1 = line([0,0], normal_vect1)
+    normal_line_2 = line([0,0], normal_vect2)
+
+    # Define boundary lines based on 2D box corners
+    bound_bot1 = line(origin, origin + vect1)
+    bound_bot2 = line(origin, origin + vect2)
+    bound_top1 = line(origin + vect2, origin + vect2 + vect1)
+    bound_top2 = line(origin + vect1, origin + vect1 + vect2)
+
+    # Identify intersection points between normal lines and the boundary lines
+    intersections = np.array([intersection(normal_line_1, bound_bot1),
+                              intersection(normal_line_2, bound_bot2),
+                              intersection(normal_line_1, bound_top1),
+                              intersection(normal_line_2, bound_top2)])
+
+    # Find distance between (0,0) and the closest intercept
+    smallest = np.min(np.linalg.norm(intersections, axis=1))
+
+    # Radius = smallest distance minus the boundary width
+    radius =  smallest - width
+
+    # Axis is along the line direction and includes point (0,0,0)
+    center1 = np.zeros(3)
+    center2 = box.vects[self.lineindex]
+
+    return Cylinder(center1, center2, radius, endcaps=False)
+
+def monopole(self,
+             sizemults: Optional[tuple] = None,
+             amin: float = 0.0,
+             bmin: float = 0.0,
+             cmin: float = 0.0,
+             shift: Optional[npt.ArrayLike] = None,
+             shiftindex: Optional[int] = None,
+             shiftscale: bool = False,
+             center: Optional[npt.ArrayLike] = None,
+             centerscale: bool = False,
+             boundaryshape: str = 'cylinder',
+             boundarywidth: float = 0.0,
+             boundaryscale: bool = False,
+             return_base_system: bool = False
+             ) -> Union[System, Tuple[System, System]]:
+    """
+    Constructs a dislocation monopole atomic configuration containing a
+    single perfectly straight dislocation. The resulting system will be
+    periodic along the box vector direction that corresponds to the
+    dislocation's line direction, and non-periodic in the other two box
+    vector directions.  Boundary atoms near the two free surfaces will be
+    identified by changing their atype values making it easy to identify
+    them later for assigning different boundary conditions.
+
+    Parameters
+    ----------
+    sizemults : tuple, optional
+        The size multipliers to use when generating the system.  Values are
+        limited to being positive integers.  The multipliers for the two
+        non-periodic directions must be even.  If not given, the default
+        multipliers will be 2 for the non-periodic directions and 1 for the
+        periodic direction.
+    amin : float, optional
+        A minimum thickness to use for the a box vector direction of the
+        final system.  Default value is 0.0.  For the non-periodic
+        directions, the resulting vector multiplier will be even.  If both
+        amin and sizemults is given, then the larger multiplier for the two
+        will be used.
+    bmin : float, optional
+        A minimum thickness to use for the b box vector direction of the
+        final system.  Default value is 0.0.  For the non-periodic
+        directions, the resulting vector multiplier will be even.  If both
+        bmin and sizemults is given, then the larger multiplier for the two
+        will be used.
+    cmin : float, optional
+        A minimum thickness to use for the c box vector direction of the
+        final system.  Default value is 0.0.  For the non-periodic
+        directions, the resulting vector multiplier will be even.  If both
+        cmin and sizemults is given, then the larger multiplier for the two
+        will be used.
+    shift : array-like object, optional
+        A rigid body shift to apply to the rotated cell prior to inserting
+        the dislocation.  Should be selected such that the ideal slip plane
+        does not correspond to any atomic planes.  Is taken as absolute if
+        shiftscale is False, or relative to the rotated cell's box vectors
+        if shiftscale is True.  Cannot be given with shiftindex.  If
+        neither shift nor shiftindex is given will use the shift set during
+        class initialization.
+    shiftindex : float, optional
+        The index of the identified optimum shifts based on the rotated
+        cell to use.  Different values allow for the selection of different
+        atomic planes neighboring the slip plane.  Note that shiftindex
+        values only apply shifts normal to the slip plane; best shifts for
+        non-planar dislocations (like bcc screw) may also need a shift in
+        the slip plane.  Cannot be given with shiftindex.  If neither shift
+        nor shiftindex is given then shiftindex = 0 is used then will use
+        the shift set during class initialization.
+    shiftscale : bool, optional
+        If False (default), a given shift value will be taken as absolute
+        Cartesian.  If True, a given shift will be taken relative to the
+        rotated cell's box vectors.
+    center : array-like object or None, optional
+        Indicates where the dislocation is positioned in the system relative
+        to the default position at (0, 0) along the box vectors associated
+        with the dislocation solution's m- and n-axes.
+    centerscale : bool, optional
+        If False (default), a given center value will be taken as absolute
+        Cartesian.  If True, a given center will be taken relative to the
+        rotated cell's box vectors.
+    boundaryshape : str, optional
+        Indicates the shape of the boundary region to use.  Options are
+        'cylinder' (default) and 'box'.  For 'cylinder', the non-boundary
+        region is defined by a cylinder with axis along the dislocation
+        line and a radius that ensures the boundary is at least
+        boundarywidth thick.  For 'box', the boundary region will be
+        exactly boundarywidth thick all around.
+    boundarywidth : float, optional
+        The width of the boundary region to apply.  Default value is 0.0,
+        i.e. no boundary region.  All atoms in the boundary region will
+        have their atype values changed.
+    boundaryscale : bool, optional
+        If False (Default), the boundarywidth will be taken as absolute.
+        If True, the boundarywidth will be taken relative to the magnitude
+        of the unit cell's a box vector.
+    return_base_system : bool, optional
+        If True then the dislocation-free base system corresponding to the
+        dislocation system will also be returned.  The base system is used
+        as a reference state for most of the dislocation analysis tools.
+
+    Returns
+    -------
+    base_system : atomman.System
+        The base "perfect crystal" reference system associated with the
+        dislocation system. Only returned if return_base_system is True.
+    disl_system : atomman.System
+        The generated dislocation monopole system.
+    """
+    # Set default sizemults
+    if sizemults is None:
+        sizemults = [2,2,2]
+        sizemults[self.lineindex] = 1
+    else:
+        sizemults = deepcopy(sizemults)
+        try:
+            assert len(sizemults) == 3
+            assert isinstance(sizemults[0], int) and sizemults[0] > 0
+            assert isinstance(sizemults[1], int) and sizemults[1] > 0
+            assert isinstance(sizemults[2], int) and sizemults[2] > 0
+            assert sizemults[self.lineindex - 1] % 2 == 0
+            assert sizemults[self.lineindex - 2] % 2 == 0
+        except AssertionError as err:
+            raise TypeError('Invalid sizemults: must be 3 positive integers, and the two not along the dislocation line must be even') from err
+
+    # Adjust multipliers based on min parameters
+    if amin > 0.0:
+        amult = int(np.ceil(amin / self.rcell.box.a))
+        if self.lineindex != 0 and amult % 2 == 1:
+            amult += 1
+        if amult > sizemults[0]:
+            sizemults[0] = amult
+
+    if bmin > 0.0:
+        bmult = int(np.ceil(bmin / self.rcell.box.b))
+        if self.lineindex != 1 and bmult % 2 == 1:
+            bmult += 1
+        if bmult > sizemults[1]:
+            sizemults[1] = bmult
+
+    if cmin > 0.0:
+        cmult = int(np.ceil(cmin / self.rcell.box.c))
+        if self.lineindex != 2 and cmult % 2 == 1:
+            cmult += 1
+        if cmult > sizemults[2]:
+            sizemults[2] = cmult
+
+    # Modify the non-periodic size multipliers
+    sizemults[self.lineindex] = (0, sizemults[self.lineindex])
+    sizemults[self.lineindex - 1] = (-sizemults[self.lineindex - 1] // 2,
+                                        sizemults[self.lineindex - 1] // 2)
+    sizemults[self.lineindex - 2] = (-sizemults[self.lineindex - 2] // 2,
+                                        sizemults[self.lineindex - 2] // 2)
+
+    # Handle shift parameters
+    if shift is not None or shiftindex is not None:
+        self.set_shift(shift, shiftindex, shiftscale)
+    shift = self.shift
+
+    # Handle center parameter
+    if center is None:
+        center = np.array([0,0,0])
+    else:
+        center = np.asarray(center)
+    if centerscale:
+        center = self.rcell.box.vector_crystal_to_cartesian(center)
+
+    # Handle boundary parameters
+    if boundaryscale is True:
+        boundarywidth = boundarywidth * self.ucell.box.a
+    if boundaryshape not in ['cylinder', 'box']:
+        raise ValueError('boundaryshape must be "cylinder" or "box"')
+
+    # Create the system where the dislocation will be inserted
+    base_system = self.rcell.supersize(*sizemults)
+    base_system.atoms.pos += shift
+    base_system.wrap()
+
+    # Copy the system and displace atoms according to the dislocation solution
+    disl_system = deepcopy(base_system)
+    disl_system.atoms.pos += self.dislsol.displacement(disl_system.atoms.pos - center)
+    disl_system.pbc = [False, False, False]
+    disl_system.pbc[self.lineindex] = True
+    disl_system.wrap()
+
+    self.set_systems(base_system, disl_system)
+
+    # Apply boundary region
+    if boundarywidth > 0.0:
+
+        if boundaryshape == 'box':
+            shape = self.box_boundary(base_system.box, boundarywidth)
+
+        elif boundaryshape == 'cylinder':
+            shape = self.cylinder_boundary(base_system.box, boundarywidth)
+
+        # Change atypes of atoms outside box
+        disl_system.atoms.atype[shape.outside(disl_system.atoms.pos)] += base_system.natypes
+        disl_system.symbols = 2 * base_system.symbols
+
+    if return_base_system:
+        return base_system, disl_system
+    else:
+        return disl_system

atomman/source/atomman/defect/Dislocation/_periodicarray.py

@@ -0,0 +1,450 @@
+# coding: utf-8
+# Standard Python libraries
+from copy import deepcopy
+from typing import Optional, Tuple, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# atomman imports
+import atomman.unitconvert as uc
+from ... import Box, System
+from ...region import PlaneSet
+
+def array_boundary(self,
+                   box: Box,
+                   width: float) -> PlaneSet:
+    """
+    Constructs a shape associated with the boundary regions used by the
+    periodicarray() generation method.  The returned shape will encompass
+    all atoms except those within width distance of the non-periodic
+    surface.
+
+    Parameters
+    ----------
+    box : atomman.Box
+        The box associated with the full (base) system.
+    width : float
+        The width of the boundary region
+
+    Returns
+    -------
+    atomman.region.PlaneSet
+        The Shape object excluding the boundary region
+    """
+    # Get plane shapes for the two non-periodic directions
+    planes = [box.planes[self.cutindex], box.planes[self.cutindex + 3]]
+
+    # Shift plane points by width in the plane normal directions
+    for plane in planes:
+        plane.point -= width * plane.normal
+
+    # Create and return shape
+    return PlaneSet(planes)
+
+def periodicarray(self,
+                  sizemults: Optional[tuple] = None,
+                  amin: float = 0.0,
+                  bmin: float = 0.0,
+                  cmin: float = 0.0,
+                  shift: Optional[npt.ArrayLike] = None,
+                  shiftindex: Optional[int] = None,
+                  shiftscale: bool = False,
+                  center: Optional[npt.ArrayLike] = None,
+                  centerscale: bool = False,
+                  boundarywidth: float = 0.0,
+                  boundaryscale: bool = False,
+                  linear: bool = False,
+                  cutoff: Optional[float] = None,
+                  return_base_system: bool = False
+                  ) -> Union[System, Tuple[System, System]]:
+    """
+    Constructs a dislocation monopole atomic configuration containing a
+    single perfectly straight dislocation. The resulting system will be
+    periodic along the box vector direction that corresponds to the
+    dislocation's line direction, and non-periodic in the other two box
+    vector directions.  Boundary atoms near the two free surfaces will be
+    identified by changing their atype values making it easy to identify
+    them later for assigning different boundary conditions.
+
+    Parameters
+    ----------
+    sizemults : tuple, optional
+        The size multipliers to use when generating the system.  Values
+        are limited to being positive integers.  The multipliers for the
+        two non-periodic directions must be even.  If not given, the
+        default multipliers will be 2 for the non-periodic directions and
+        1 for the periodic direction.
+    amin : float, optional
+        A minimum thickness to use for the a box vector direction of the
+        final system.  Default value is 0.0.  For the non-periodic
+        directions, the resulting vector multiplier will be even.  If both
+        amin and sizemults is given, then the larger multiplier for the two
+        will be used.
+    bmin : float, optional
+        A minimum thickness to use for the b box vector direction of the
+        final system.  Default value is 0.0.  For the non-periodic
+        directions, the resulting vector multiplier will be even.  If both
+        bmin and sizemults is given, then the larger multiplier for the two
+        will be used.
+    cmin : float, optional
+        A minimum thickness to use for the c box vector direction of the
+        final system.  Default value is 0.0.  For the non-periodic
+        directions, the resulting vector multiplier will be even.  If both
+        cmin and sizemults is given, then the larger multiplier for the two
+        will be used.
+    shift : float, optional
+        A rigid body shift to apply to the rotated cell prior to inserting
+        the dislocation.  Should be selected such that the ideal slip plane
+        does not correspond to any atomic planes.  Is taken as absolute if
+        shiftscale is False, or relative to the rotated cell's box vectors
+        if shiftscale is True.  Cannot be given with shiftindex.  If
+        neither shift nor shiftindex is given then shiftindex = 0 is used.
+    shiftindex : float, optional
+        The index of the identified optimum shifts based on the rotated
+        cell to use.  Different values allow for the selection of different
+        atomic planes neighboring the slip plane.  Note that shiftindex
+        values only apply shifts normal to the slip plane; best shifts for
+        non-planar dislocations (like bcc screw) may also need a shift in
+        the slip plane.  Cannot be given with shiftindex.  If neither shift
+        nor shiftindex is given then shiftindex = 0 is used.
+    shiftscale : bool, optional
+        If False (default), a given shift value will be taken as absolute
+        Cartesian.  If True, a given shift will be taken relative to the
+        rotated cell's box vectors.
+    center : array-like object or None, optional
+        Indicates where the dislocation is positioned in the system relative
+        to the default position at (0, 0) along the box vectors associated
+        with the dislocation solution's m- and n-axes.
+    centerscale : bool, optional
+        If False (default), a given center value will be taken as absolute
+        Cartesian.  If True, a given center will be taken relative to the
+        rotated cell's box vectors.
+    boundarywidth : float, optional
+        The width of the boundary region to apply.  Default value is 0.0,
+        i.e. no boundary region.  All atoms in the boundary region will
+        have their atype values changed and will be displaced by linear
+        displacements.
+    boundaryscale : bool, optional
+        If False (Default), the boundarywidth will be taken as absolute.
+        If True, the boundarywidth will be taken relative to the magnitude
+        of the unit cell's a box vector.
+    linear : bool, optional
+        If True, then only linear displacements will be used and not the
+        dislocation solution.  Using only linear displacements is useful
+        for screw dislocations and dislocations with large stacking fault
+        distances.  If False (default) then the dislocation solution will
+        be used for the middle displacements and linear displacements only
+        in the boundary region.
+    cutoff : float, optional
+        Cutoff distance to use for identifying duplicate atoms to remove.
+        For dislocations with an edge component, applying the displacements
+        creates an extra half-plane of atoms that will have (nearly)
+        identical positions with other atoms after altering the boundary
+        conditions.  Default value is 0.5 Angstrom.
+    return_base_system : bool, optional
+        If True then the dislocation-free base system corresponding to the
+        dislocation system will also be returned.  The base system is used
+        as a reference state for most of the dislocation analysis tools.
+
+    Returns
+    -------
+    base_system : atomman.System
+        The base "perfect crystal" reference system associated with the
+        dislocation system.  If the Burgers vector has an edge component
+        then the atoms deleted when generating disl_system will also be 
+        deleted from base_system. Only returned if return_base_system is
+        True.
+    disl_system : atomman.System
+        The generated periodic array of dislocations system.
+    """
+    # Set default sizemults
+    if sizemults is None:
+        sizemults = [2,2,2]
+        sizemults[self.lineindex] = 1
+    else:
+        try:
+            assert len(sizemults) == 3
+            assert isinstance(sizemults[0], int) and sizemults[0] > 0
+            assert isinstance(sizemults[1], int) and sizemults[1] > 0
+            assert isinstance(sizemults[2], int) and sizemults[2] > 0
+            assert sizemults[self.lineindex - 1] % 2 == 0
+            assert sizemults[self.lineindex - 2] % 2 == 0
+        except AssertionError as err:
+            raise TypeError('Invalid sizemults: must be 3 positive integers, and the two not along the dislocation line must be even') from err
+
+    # Adjust multipliers based on min parameters
+    if amin > 0.0:
+        amult = int(np.ceil(amin / self.rcell.box.a))
+        if self.lineindex != 0 and amult % 2 == 1:
+            amult += 1
+        if amult > sizemults[0]:
+            sizemults[0] = amult
+
+    if bmin > 0.0:
+        bmult = int(np.ceil(bmin / self.rcell.box.b))
+        if self.lineindex != 1 and bmult % 2 == 1:
+            bmult += 1
+        if bmult > sizemults[1]:
+            sizemults[1] = bmult
+
+    if cmin > 0.0:
+        cmult = int(np.ceil(cmin / self.rcell.box.c))
+        if self.lineindex != 2 and cmult % 2 == 1:
+            cmult += 1
+        if cmult > sizemults[2]:
+            sizemults[2] = cmult
+
+    # Modify the non-periodic size multipliers
+    sizemults[self.lineindex] = (0, sizemults[self.lineindex])
+    sizemults[self.lineindex - 1] = (-sizemults[self.lineindex - 1] // 2,
+                                        sizemults[self.lineindex - 1] // 2)
+    sizemults[self.lineindex - 2] = (-sizemults[self.lineindex - 2] // 2,
+                                        sizemults[self.lineindex - 2] // 2)
+
+    # Handle shift parameters
+    if shift is not None or shiftindex is not None:
+        self.set_shift(shift, shiftindex, shiftscale)
+    shift = self.shift
+
+    # Handle center parameter
+    if center is None:
+        center = np.array([0,0,0])
+    else:
+        center = np.asarray(center)
+    if centerscale:
+        center = self.rcell.box.vector_crystal_to_cartesian(center)
+
+    # Handle boundary parameters
+    if boundaryscale is True:
+        boundarywidth = boundarywidth * self.ucell.box.a
+
+    # Create the system where the dislocation will be inserted
+    base_system = self.rcell.supersize(*sizemults)
+    base_system.atoms.pos += shift
+    base_system.wrap()
+
+    # Create the dislocation system
+    disl_system = self.build_disl_array(base_system, center, linear=linear,
+                                        bwidth=boundarywidth, cutoff=cutoff)
+    # Trim deleted atoms from base_system
+    base_system = base_system.atoms_ix[disl_system.atoms.old_id]
+
+    # Apply boundary region
+    if boundarywidth > 0.0:
+
+        shape = self.array_boundary(base_system.box, boundarywidth)
+
+        # Change atypes of atoms outside box
+        disl_system.atoms.atype[shape.outside(disl_system.atoms.pos)] += base_system.natypes
+        disl_system.symbols = 2 * base_system.symbols
+
+    self.set_systems(base_system, disl_system)
+
+    if return_base_system:
+        return base_system, disl_system
+    else:
+        return disl_system
+
+
+def build_disl_array(self,
+                     base_system: System,
+                     center: npt.ArrayLike,
+                     linear: bool = False,
+                     bwidth: Optional[float] = None,
+                     cutoff: Optional[float] = None,
+                     ) -> System:
+    """
+    Method that converts a bulk crystal system into a periodic array of
+    dislocations.  A single dislocation is inserted using a dislocation
+    solution.  The system's box and pbc are altered such that the system is
+    periodic and compatible across the two box vectors contained in the slip
+    plane.  The third box vector is non-periodic, resulting in free surfaces
+    parallel to the dislocation's slip plane.
+
+    Parameters
+    ----------
+    base_system : atomman.System
+        A perfect, bulk atomic system.
+    dislsol : atomman.defect.VolterraDislocation, optional
+        A dislocation solution to use to displace atoms by.  If not given,
+        all atoms will be given linear displacements associated with the
+        long-range limits.
+    m : array-like object, optional
+        The dislocation solution m unit vector.  This vector is in the slip
+        plane and perpendicular to the dislocation line direction.  Only needed
+        if dislsol is not given.
+    n : array-like object, optional
+        The dislocation solution n unit vector.  This vector is normal to the 
+        slip plane.  Only needed if dislsol is not given.
+    burgers : array-like object, optional
+        The Cartesian Burger's vector for the dislocation relative to the
+        given system's Cartesian coordinates.  Only needed if dislsol is not
+        given.
+    bwidth : float, optional
+        The width of the boundary region at the free surfaces.  Atoms within
+        the boundaries will be displaced by linear displacements instead of
+        by the dislocation solution.  Only given if dislsol is not None.
+        Default value if dislsol is given is 10 Angstroms.
+    cutoff : float, optional
+        Cutoff distance to use for identifying duplicate atoms to remove.
+        For dislocations with an edge component, applying the displacements
+        creates an extra half-plane of atoms that will have (nearly) identical
+        positions with other atoms after altering the boundary conditions.
+        Default cutoff value is 0.5 Angstrom.
+
+    Returns
+    -------
+    atomman.System
+        The resulting periodic array of dislocations system.  An additional
+        atoms property 'old_id' will be added to map the atoms in the defect
+        system back to the associated atoms in the original system.
+    """
+
+    # ------------------------ Parameter handling --------------------------- #
+
+    # Set default values
+    if bwidth is None:
+        bwidth = uc.set_in_units(10, 'angstrom')
+    if cutoff is None:
+        cutoff = uc.set_in_units(0.5, 'angstrom')
+
+    # Extract dislocation solution values
+    m = self.dislsol.m
+    n = self.dislsol.n
+    burgers = self.dislsol.burgers
+
+    # Extract system values
+    pos = base_system.atoms.pos
+    vects = base_system.box.vects
+    spos = base_system.atoms_prop(key='pos', scale=True)
+
+    # Extract orientation values
+    lineindex = self.lineindex
+    cutindex = self.cutindex
+    motionindex = self.motionindex
+
+    # Check for atoms exactly on the slip plane
+    if np.isclose(spos[:, cutindex], 0.5, rtol=0).sum() > 0:
+        raise ValueError("atom positions found on slip plane: apply a coordinate shift")
+
+    # ---------------------- Boundary modification -------------------------- #
+
+    # Modify box vector in the motion direction by +- burgers/2
+    newvects = deepcopy(vects)
+    if burgers.dot(m) > 0:
+        newvects[motionindex] -= burgers / 2
+    else:
+        newvects[motionindex] += burgers / 2
+    newbox = Box(vects=newvects, origin=base_system.box.origin)
+
+    # Make boundary condition perpendicular to slip plane non-periodic
+    newpbc = [True, True, True]
+    newpbc[cutindex] = False
+
+    # Get length of system along motionindex
+    # WHICH IS BEST!?!?!?
+    length = np.abs(vects[motionindex].dot(m))
+    #length = np.linalg.norm(newvects[motionindex])
+
+    # -------------------- duplicate atom identification -------------------- #
+
+    # Create test system to identify "duplicate" atoms
+    testsystem = System(atoms=deepcopy(base_system.atoms), box=newbox,
+                           pbc=newpbc, symbols=base_system.symbols)
+
+    # Apply linear gradient shift to all atoms
+    testsystem.atoms.pos += linear_displacement(pos - center, burgers, length, m, n)
+    testsystem.atoms.old_id = range(testsystem.natoms)
+
+    # Identify atoms at the motionindex boundary to include in the duplicate check
+    spos = testsystem.atoms_prop(key='pos', scale=True)
+    sburgers = np.abs(2 * burgers[motionindex] / (length))
+    boundaryatoms = testsystem.atoms[  (spos[:, motionindex] < sburgers) 
+                                     | (spos[:, motionindex] > 1.0 - sburgers) ]
+
+    # Compare distances between boundary atoms to identify duplicates
+    dup_atom_ids = []
+    for ni, i in enumerate(boundaryatoms.old_id[:-1]):
+        js = boundaryatoms.old_id[ni+1:]
+        try:
+            distances = np.linalg.norm(testsystem.dvect(i, js), axis=1)
+            mindistance = distances.min()
+        except:
+            mindistance = np.linalg.norm(testsystem.dvect(i, js))
+        if mindistance < cutoff:
+            dup_atom_ids.append(i)
+    ii = np.ones(base_system.natoms, dtype=bool)
+    ii[dup_atom_ids] = False
+
+    # Count found duplicate atoms
+    found = base_system.natoms - ii.sum()
+
+    # Count expected number of duplicates based on volume change
+    expected = base_system.natoms - (base_system.natoms * newbox.volume / base_system.box.volume)
+    if np.isclose(expected, round(expected)):
+        expected = int(round(expected))
+    else:
+        raise ValueError('expected number of atoms to delete not an integer: check burgers vector')
+
+    # Compare found versus expected number of atoms
+    if found != expected:
+        raise ValueError('Deleted atom mismatch: expected %i, found %i. Adjust system dimensions and/or cutoff' %(expected, found))
+
+    # ---------------------- Build dislocation system ----------------------- #
+
+    # Generate new system with duplicate atoms removed
+    disl_system = System(atoms=base_system.atoms[ii], box=newbox, pbc=newpbc,
+                         symbols=base_system.symbols)
+
+    # Define old_id so atoms in newsystem can be mapped back to system
+    disl_system.atoms.old_id = np.where(ii)[0]
+
+    if linear:
+        # Use only linear displacements
+        disp = linear_displacement(disl_system.atoms.pos - center, burgers, length, m, n)
+    
+    else:
+        # Identify boundary atoms
+        miny = base_system.box.origin.dot(n)
+        maxy = miny + vects[cutindex].dot(n)
+        if maxy < miny:
+            miny, maxy = maxy, miny
+        y = disl_system.atoms.pos.dot(n)
+        ii = np.where((y <= miny + bwidth) | (y >= maxy - bwidth))
+        
+        # Use dislsol in middle and linear displacements at boundary
+        disp = self.dislsol.displacement(disl_system.atoms.pos - center)
+        disp[:, cutindex] -= disp[:, cutindex].mean()
+        disp[ii] = linear_displacement(disl_system.atoms.pos[ii] - center, burgers,
+                                       length, m, n)
+    
+    # Displace atoms and wrap
+    disl_system.atoms.pos += disp
+    disl_system.wrap()
+    
+    return disl_system
+    
+def linear_displacement(pos, burgers, length, m, n):
+    """
+    Computes linear displacements associated with a dislocation in a system.
+    
+    Parameters
+    ----------
+    pos : array-like object
+        List of Cartesian atomic positions.
+    burgers : array-like object
+        The Cartesian Burgers vector
+    length : float
+        The total length of the system along the m direction.
+    m : array-like object, optional
+        The dislocation solution m unit vector.  This vector is in the slip
+        plane and perpendicular to the dislocation line direction.  Only needed
+        if dislsol is not given.
+    n : array-like object, optional
+        The dislocation solution n unit vector.  This vector is normal to the 
+        slip plane.  Only needed if dislsol is not given.
+    """
+
+    return np.outer(np.sign(pos.dot(n)) * (0.25 - pos.dot(m) / (2 * length)), burgers)

atomman/source/atomman/defect/FreeSurface.py

@@ -0,0 +1,634 @@
+# coding: utf-8
+# Standard Python libraries
+import io
+from itertools import product
+from typing import Optional, Tuple, Union
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+from yabadaba.record import Record
+
+from . import free_surface_basis
+from ..tools import miller
+from ..region import Plane
+from .. import System, load
+from ..library import load_record, Database
+
+try:
+    import spglib
+    has_spglib = True
+except ImportError:
+    has_spglib = False
+
+class FreeSurface():
+    """
+    Class for generating free surface atomic configurations using clean planar slices.
+    """
+
+    def __init__(self,
+                 hkl: npt.ArrayLike,
+                 ucell: System,
+                 cutboxvector: str = 'c',
+                 maxindex: Optional[int] = None,
+                 conventional_setting: str = 'p',
+                 shift: Optional[npt.ArrayLike] = None,
+                 shiftindex: Optional[int] = None,
+                 shiftscale: bool = False,
+                 tol: float = 1e-7):
+        """
+        Class initializer.  Identifies the proper rotations for the given hkl plane
+        and cutboxvector, and creates the rotated cell.
+
+        Parameters
+        ----------
+        hkl : array-like object
+            The free surface plane to generate expressed in either 3 indices
+            Miller (hkl) format or 4 indices Miller-Bravais (hkil) format.
+        ucell : atomman.System
+            The unit cell to use in generating the system.
+        cutboxvector : str, optional
+            Specifies which of the three box vectors corresponds to the
+            out-of-plane vector.  Default value is c.
+        maxindex : int, optional
+            Max uvw index value to use in identifying the best uvw set for the
+            out-of-plane vector.  If not given, will use the largest absolute
+            index between the given hkl and the initial in-plane vector guesses.
+        conventional_setting : str, optional
+            Indicates the space lattice setting of the given unit cell, i.e.
+            'p' for primitive, 'i' for body-centered, 'f' for face-centered,
+            'a', 'b', or 'c' for side-centered and 't1', or 't2' for trigonal
+            in a hexagonal setting.  Setting this with the appropriate
+            conventional unit cell allows for identifying lattice vectors that
+            are not integers with respect to the conventional unit cell.  This
+            also creates the rotated cell from a compatible primitive cell,
+            thereby the final dislocation configurations can be smaller than
+            possible solely from the conventional unit cell.
+        shift : array-like object, optional
+            Applies a shift to all atoms. Different values allow for free surfaces with
+            different termination planes to be selected.  shift is taken as absolute
+            if shiftscale is False, or relative to the rotated cell's box vectors
+            if shiftscale is True.  Cannot be given with shiftindex.  If
+            neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftindex : float, optional
+            The index of the identified shifts based on the rotated
+            cell to use.  Different values allow for the selection of different
+            atomic planes neighboring the slip plane.  Cannot be given with shift.
+            If neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftscale : bool, optional
+            If False (default), a given shift value will be taken as absolute
+            Cartesian.  If True, a given shift will be taken relative to the
+            rotated cell's box vectors.
+        tol : float, optional
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        """
+
+        # Pass parameters to free_surface_basis to get the rotation uvws
+        uvws = free_surface_basis(hkl, box=ucell.box, cutboxvector=cutboxvector, maxindex=maxindex,
+                                  conventional_setting=conventional_setting)
+
+        # Generate the rotated cell
+        # rcell.box.vects == uvws @ ucell.box.vects @ transform.T
+        rcell, transform = ucell.rotate(uvws, return_transform=True)
+
+        # Transform uvws to the conventional cell representation
+        if uvws.shape == (3,3):
+            uvws = miller.vector_primitive_to_conventional(uvws, conventional_setting)
+
+        # Set cutindex and rcellwidth based on cutboxvector
+        if cutboxvector == 'a':
+            if rcell.box.bvect[0] != 0.0 or rcell.box.cvect[0] != 0.0:
+                raise ValueError("box bvect and cvect cannot have x component for cutboxvector='a'")
+            cutindex = 0
+
+        elif cutboxvector == 'b':
+            if rcell.box.avect[1] != 0.0 or rcell.box.cvect[1] != 0.0:
+                raise ValueError("box avect and cvect cannot have y component for cutboxvector='b'")
+            cutindex = 1
+
+        elif cutboxvector == 'c':
+            if rcell.box.avect[2] != 0.0 or rcell.box.bvect[2] != 0.0:
+                raise ValueError("box avect and bvect cannot have z component for cutboxvector='c'")
+            cutindex = 2
+
+        # Define out of plane unit vector
+        ovect = np.zeros(3)
+        ovect[cutindex] = 1.0
+
+        # Get out of plane width
+        rcellwidth = rcell.box.vects[cutindex, cutindex]
+
+        # Get the unique coordinates normal to the plane
+        pos = rcell.atoms.pos
+        numdec = - int(np.floor(np.log10(tol)))
+        _, unique_indices = np.unique(pos[:, cutindex].round(numdec), return_index=True)
+        coords = pos[unique_indices, cutindex]
+
+        # Add periodic replica if missing
+        if not np.isclose(coords[-1] - coords[0], rcellwidth, rtol=0.0, atol=tol):
+            coords = np.append(coords, coords[0] + rcellwidth)
+
+        # Compute the shifts
+        relshifts = rcellwidth - (coords[1:] + coords[:-1]) / 2
+        relshifts[relshifts > rcellwidth] -= rcellwidth
+        relshifts[relshifts < 0.0] += rcellwidth
+        shifts = np.outer(np.sort(relshifts), ovect)
+
+        # Save attributes
+        self.__hkl = np.asarray(hkl)
+        self.__ucell = ucell
+        self.__rcell = rcell
+        self.__cutboxvector = cutboxvector
+        self.__cutindex = cutindex
+        self.__uvws = uvws
+        self.__rcellwidth = rcellwidth
+        self.__shifts = shifts
+        self.__transform = transform
+        self.__conventional_setting = conventional_setting
+        self.__system = None
+        self.__surfacearea = None
+
+        # Set shift
+        self.set_shift(shift=shift, shiftindex=shiftindex, shiftscale=shiftscale)
+
+    @classmethod
+    def fromrecord(cls,
+                   record: Union[str, io.IOBase, DM, Record],
+                   ucell: Union[System, str, io.IOBase],
+                   maxindex: Optional[int] = None,
+                   tol: float = 1e-7):
+        """
+        Construct a FreeSurface object based on parameters in a free_surface
+        record and unit cell information.
+
+        Parameters
+        ----------
+        record : atomman.library.record.FreeSurface, str, file-like object or DataModelDict
+            A FreeSurface record object or the model contents for one.
+        ucell : atomman.System
+            The unit cell to use in generating the system.
+        maxindex : int, optional
+            Max uvw index value to use in identifying the best uvw set for the
+            out-of-plane vector.  If not given, will use the largest absolute
+            index between the given hkl and the initial in-plane vector guesses.
+        tol : float, optional
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        """
+        # Create record object if needed
+        if not isinstance(record, Record):
+            record = load_record('free_surface', model=record)
+
+        # Extract parameters in the record
+        hkl = miller.fromstring(record.parameters['hkl'])
+        shiftindex = int(record.parameters.get('shiftindex', 0))
+        cutboxvector = record.parameters['cutboxvector']
+        conventional_setting = record.parameters.get('conventional_setting', 'p')
+
+        return cls(hkl=hkl, ucell=ucell, cutboxvector=cutboxvector,
+                   maxindex=maxindex, shiftindex=shiftindex,
+                   conventional_setting=conventional_setting, tol=tol)
+
+    @classmethod
+    def fromdatabase(cls,
+                     name: Optional[str] = None,
+                     ucell: Optional[System] = None,
+                     database: Optional[Database] = None,
+                     prompt: bool = True,
+                     maxindex: Optional[int] = None,
+                     tol: float = 1e-7,
+                     **kwargs):
+        """
+        Construct a FreeSurface object based on record(s) retrieved from the
+        reference database.
+
+        Parameters
+        ----------
+        name : str or None, optional
+            The name of the free_surface record to retrieve from the database.
+            Alternatively, you can use any other query keyword arguments supported
+            by the free_surface record style (see **kwargs below for more info).
+        ucell : atomman.System or None, optional
+            The unit cell to use in generating the system.  If None (default), then
+            the crystal_prototype record that matches the defect's family setting
+            will be loaded from the database.  Note that if None then the
+            crystal-specific info (lattice constants and symbols) should be given
+            here as kwargs (see below).
+        database : atomman.library.Database or None, optional
+            A Database object to use to fetch the records.  If None (default), then
+            a new Database instance will be created.
+        prompt : bool
+            If prompt=True (default) then a screen input will ask for a selection
+            if multiple matching free_surface (or crystal_prototype) records are
+            found.  If prompt=False, then an error will be thrown if multiple
+            matches are found.
+        maxindex : int, optional
+            Max uvw index value to use in identifying the best uvw set for the
+            out-of-plane vector.  If not given, will use the largest absolute
+            index between the given hkl and the initial in-plane vector guesses.
+        tol : float, optional
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        **kwargs : any
+            The recognized kwargs include the query keywords for free_surface
+            records (key, id, family, hkl, shiftindex, cutboxvector), and the
+            crystal-specific parameters recognized by the prototype load style
+            (a, b, c, alpha, beta, gamma, symbols).  The non-trivial
+            crystal-specific parameters should be for the crystal if ucell is
+            not given above as the crystal prototype lacks this information.
+        """
+        # Initialize a database if needed
+        if database is None:
+            database = Database()
+
+        # Extract ucell parameters from kwargs
+        prototype_kwargs = {}
+        prototype_kwargs_names = ['a', 'b', 'c', 'alpha', 'beta', 'gamma', 'symbols']
+        for prototype_kwargs_name in prototype_kwargs_names:
+            if prototype_kwargs_name in kwargs:
+                prototype_kwargs[prototype_kwargs_name] = kwargs.pop(prototype_kwargs_name)
+
+        # Fetch matching defect record
+        record = database.get_record('free_surface', name=name, prompt=prompt, **kwargs)
+
+        # Fetch crystal prototype unit cell if needed
+        if ucell is None:
+            ucell = load('prototype', name=record.family, **prototype_kwargs)
+        else:
+            if len(prototype_kwargs) > 0:
+                raise ValueError('crystal-specific kwargs cannot be given with ucell')
+
+        return cls.fromrecord(record=record, ucell=ucell, maxindex=maxindex, tol=tol)
+
+    @property
+    def hkl(self) -> np.ndarray:
+        """numpy.ndarray : Crystal plane in Miller or Miller-Bravais indices"""
+        return self.__hkl
+
+    @property
+    def ucell(self) -> System:
+        """atomman.System : The unit cell to use in building the defect system."""
+        return self.__ucell
+
+    @property
+    def rcell(self) -> System:
+        """atomman.System : the rotated cell to use in building the defect system."""
+        return self.__rcell
+
+    @property
+    def cutboxvector(self) -> str:
+        """str : The box vector for the cut direction."""
+        return self.__cutboxvector
+
+    @property
+    def cutindex(self) -> int:
+        """int : The Cartesian index for the cut direction."""
+        return self.__cutindex
+
+    @property
+    def uvws(self) -> np.ndarray:
+        """
+        numpy.ndarray : The conventional Miller or Miller-Bravais crystal
+        vectors associated with the rcell box vectors.
+        """
+        return self.__uvws
+
+    @property
+    def rcellwidth(self) -> float:
+        """float : The width of rcell in the cutindex direction."""
+        return self.__rcellwidth
+
+    @property
+    def shifts(self) -> list:
+        """list : All shift values that place the fault halfway between atomic layers in rcell."""
+        return self.__shifts
+
+    @property
+    def shift(self) -> np.ndarray:
+        """
+        numpy.NDArray : The particular shift value that will be or was used to
+        construct the defect system
+        """
+        return self.__shift
+
+    @property
+    def system(self) -> System:
+        """atomman.System : The built free surface system."""
+        if self.__system is not None:
+            return self.__system
+        else:
+            raise AttributeError('system not yet built. Use build_system() or surface().')
+
+    @property
+    def surfacearea(self) -> float:
+        """float : The surface area of one of the hkl planes."""
+        if self.__surfacearea is not None:
+            return self.__surfacearea
+        else:
+            raise AttributeError('system not yet built. Use build_system() or surface().')
+
+    @property
+    def transform(self) -> np.ndarray:
+        """numpy.ndarray : The Cartesian transformation tensor associated with rotating from ucell to rcell"""
+        return self.__transform
+
+    @property
+    def conventional_setting(self) -> str:
+        """str : The lattice setting/centering associated with the conventional cell (used if ucell is primitive)"""
+        return self.__conventional_setting
+
+    def surface(self,
+                shift: Optional[npt.ArrayLike] = None,
+                shiftindex: Optional[int] = None,
+                shiftscale: bool = None,
+                vacuumwidth: Optional[float] = None,
+                minwidth: Optional[float] = None,
+                sizemults: Optional[list] = None,
+                even: bool = False) -> System:
+        """
+        Generates and returns a free surface atomic system.
+
+        Parameters
+        ----------
+        shift : array-like object, optional
+            Applies a shift to all atoms. Different values allow for free surfaces with
+            different termination planes to be selected.  shift is taken as absolute
+            if shiftscale is False, or relative to the rotated cell's box vectors
+            if shiftscale is True.  Cannot be given with shiftindex.  If
+            neither shift nor shiftindex is given then the current value set to the
+            shift attribute will be used.
+        shiftindex : float, optional
+            The index of the identified shifts based on the rotated
+            cell to use.  Different values allow for the selection of different
+            atomic planes neighboring the slip plane.  Cannot be given with shift.
+            If neither shift nor shiftindex is given then the current value set to
+            the shift attribute will be used.
+        shiftscale : bool, optional
+            If False (default), a given shift value will be taken as absolute
+            Cartesian.  If True, a given shift will be taken relative to the
+            rotated cell's box vectors.
+        vacuumwidth : float, optional
+            If given, the free surface is created by modifying the system's box to insert
+            a region of vacuum with this width. This is typically used for DFT calculations
+            where it is computationally preferable to insert a vacuum region and keep all
+            dimensions periodic.
+        sizemults : list or tuple, optional
+            The three System.supersize multipliers [a_mult, b_mult, c_mult] to use on the
+            rotated cell to build the final system. Note that the cutboxvector sizemult
+            must be an integer and not a tuple.  Default value is [1, 1, 1].
+        minwidth : float, optional
+            If given, the sizemult along the cutboxvector will be selected such that the
+            width of the resulting final system in that direction will be at least this
+            value. If both sizemults and minwidth are given, then the larger of the two
+            in the cutboxvector direction will be used.
+        even : bool, optional
+            A True value means that the sizemult for cutboxvector will be made an even
+            number by adding 1 if it is odd.  Default value is False.
+
+        Returns
+        -------
+        atomman.System
+            The free surface atomic system.
+        """
+
+        # Set default function values
+        if shift is not None or shiftindex is not None:
+            self.set_shift(shift=shift, shiftindex=shiftindex, shiftscale=shiftscale)
+        shift = self.shift
+
+        if sizemults is None:
+            sizemults = [1, 1, 1]
+
+        # Handle minwidth
+        if minwidth is not None:
+            mult = int(np.ceil(minwidth / self.rcellwidth))
+
+            sizemult = sizemults[self.cutindex]
+            if mult > np.abs(sizemult):
+                sizemults[self.cutindex] = np.sign(sizemult) * mult
+
+        # Handle even
+        if even and sizemults[self.cutindex] % 2 == 1:
+            if sizemults[self.cutindex] > 0:
+                sizemults[self.cutindex] += 1
+            else:
+                sizemults[self.cutindex] -= 1
+
+        # Define out of plane unit vector
+        ovect = np.zeros(3)
+        ovect[self.cutindex] = 1.0
+
+        # Supersize and shift the system
+        system = self.rcell.supersize(*sizemults)
+        system.atoms.pos += shift
+        system.wrap()
+
+        # Change system's pbc
+        system.pbc = [True, True, True]
+        system.pbc[self.cutindex] = False
+
+        # Insert vacuumwidth
+        if vacuumwidth is not None:
+            if vacuumwidth < 0:
+                raise ValueError('vacuumwidth must be positive')
+            newvects = system.box.vects
+            newvects[self.cutindex, self.cutindex] += vacuumwidth
+            neworigin = system.box.origin - ovect * vacuumwidth / 2
+            system.box_set(vects=newvects, origin=neworigin)
+
+        # Compute surfacearea based on cutboxvector
+        if self.cutboxvector == 'a':
+            surfacearea = np.linalg.norm(np.cross(system.box.bvect, system.box.cvect))
+
+        elif self.cutboxvector == 'b':
+            surfacearea = np.linalg.norm(np.cross(system.box.avect, system.box.cvect))
+
+        elif self.cutboxvector == 'c':
+            surfacearea = np.linalg.norm(np.cross(system.box.avect, system.box.bvect))
+
+        # Save attributes
+        self.__system = system
+        self.__surfacearea = surfacearea
+
+        return self.system
+
+    def unique_shifts(self,
+                      symprec: float = 1e-5,
+                      trial_image_range: int = 1,
+                      atol: float = 1e-8,
+                      return_indices: bool = False
+                      ) -> Union[np.ndarray, Tuple[np.ndarray, list]]:
+        """
+        Use crystal symmetry operations to filter the list of shift values to
+        only those that are symmetrically unique.  Note that the identified
+        unique shifts can still result in the creation of energetically
+        equivalent free surfaces if the free surface introduces a symmetry
+        operation not present in the bulk crystal.
+
+        Parameters
+        ----------
+        symprec: float
+            The symmetry precision tolerance value used in spglib.
+        trial_image_range: int, more than or equal to 1.
+            Maximum cell images searched in finding translationally equivalent
+            planes.  The default value is one, which corresponds to search the
+            27 neighbor images, [-1, 1]^3.  The default value may not be
+            sufficient for largely distorted lattice.
+        atol: float
+            The absolute tolerance used in comparing two crystal planes.
+        return_indices: bool
+            If True then the indices of shift that correspond to the
+            identified unique shifts will be returned as well.  Default value
+            is False (only return the shift vectors).
+
+        Returns
+        -------
+        unique_shifts: np.ndarray, (# of unique shifts, 3)
+            The symmetrically unique shift vectors.
+        unique_indices: list
+            The indices of shifts that correspond to the identified unique
+            shifts.
+        """
+        if not has_spglib:
+            raise ImportError("FreeSurface.unique_shifts requires spglib. Use `pip install spglib`")
+        if (not isinstance(trial_image_range, int)) or (trial_image_range <= 0):
+            raise ValueError("trial_image_range should be positive integer.")
+
+        # Planes for each shift
+        normal = np.zeros(3)
+        normal[self.cutindex] = 1.0
+        planes = [Plane(normal, shift) for shift in self.shifts]
+
+        # Get symmetry operations of rotated ucell
+        vects, positions, numbers = self.ucell.dump('spglib_cell')
+        rotated_vects = np.dot(vects, self.transform.T)
+        dataset = spglib.get_symmetry_dataset((rotated_vects, positions, numbers), symprec=symprec)
+
+        # Compatibility fix for newspglib
+        if hasattr(dataset, 'rotations'):
+            dataset = {'rotations': dataset.rotations,
+                       'translations': dataset.translations,
+                       'primitive_lattice': dataset.primitive_lattice}
+
+        # Convert operations to Cartesian
+        operations = []
+        vects_tinv = np.linalg.inv(rotated_vects.T)
+        for rotation, translation in zip(dataset['rotations'], dataset['translations']):
+            rotation_cart = np.dot(np.dot(rotated_vects.T, rotation), vects_tinv)
+            translation_cart = np.inner(translation, rotated_vects.T)
+
+            # It is sufficient to consider only symmetry operation that preserve the normal vector.
+            if np.allclose(np.dot(rotation_cart, normal), normal):
+                operations.append((rotation_cart, translation_cart))
+
+        unique_shifts = []
+        unique_indices = []
+
+        # Use primitive vectors for the search if available
+        try:
+            primitive_vects = dataset['primitive_lattice']
+        except KeyError:
+            primitive_vects = rotated_vects
+
+        # List of trial displacements to search for a translation between two planes
+        # The range [-1, 1] may not be sufficient for largely distorted lattice.
+        trial_images = list(product(range(-trial_image_range, trial_image_range + 1), repeat=3))
+
+        def is_equivalent_by_primitive_vects(plane1, plane2):
+            # Check if two planes can be transformed to each other by lattice vectors
+            for image in trial_images:
+                rotation = np.eye(3)
+                translation = np.inner(image, primitive_vects.T)
+                new_plane1 = plane1.operate(rotation, translation)
+                if new_plane1.isclose(plane2, atol=atol):
+                    return True
+            return False
+
+        for i in range(len(self.shifts)-1, -1, -1):
+            plane_i = planes[i]
+
+            # Obtain symmetrically equivalent planes with the i-th plane
+            equivalent_planes = []
+            for rotation, translation in operations:
+                new_plane = plane_i.operate(rotation, translation)
+
+                # If the new plane is already found, skip it.
+                skip = False
+                for old_plane in equivalent_planes:
+                    if new_plane.isclose(old_plane, atol=atol):
+                        skip = True
+                        continue
+                if skip:
+                    continue
+                equivalent_planes.append(new_plane)
+
+            # Compare with remained shifts
+            is_unique = True
+            for j in range(i-1, -1, -1):
+                plane_j = planes[j]
+                # Here, the two planes have the normal vector.
+                for plane in equivalent_planes:
+                    if is_equivalent_by_primitive_vects(plane, plane_j):
+                        is_unique = False
+                        break
+
+                if not is_unique:
+                    break
+
+            if is_unique:
+                unique_indices.append(i)
+
+        unique_indices.sort()
+        unique_shifts = self.shifts[unique_indices]
+
+        if return_indices is True:
+            return unique_shifts, unique_indices
+        return unique_shifts
+
+    def set_shift(self,
+                  shift: Optional[npt.ArrayLike] = None,
+                  shiftindex: Optional[int] = None,
+                  shiftscale: bool = False):
+        """
+        Directly set the shift value based on shiftindex, or shift and shiftscale.
+        NOTE that the shift value can alternatively be set during class initialization
+        or when surface() is called.
+
+        Parameters
+        ----------
+        shift : array-like object, optional
+            Applies a shift to all atoms. Different values allow for free surfaces with
+            different termination planes to be selected.  shift is taken as absolute
+            if shiftscale is False, or relative to the rotated cell's box vectors
+            if shiftscale is True.  Cannot be given with shiftindex.  If
+            neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftindex : float, optional
+            The index of the identified shifts based on the rotated
+            cell to use.  Different values allow for the selection of different
+            atomic planes neighboring the slip plane.  Cannot be given with shift.
+            If neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftscale : bool, optional
+            If False (default), a given shift value will be taken as absolute
+            Cartesian.  If True, a given shift will be taken relative to the
+            rotated cell's box vectors.
+        """
+        # Handle shift parameters
+        if shift is not None:
+            if shiftindex is not None:
+                raise ValueError('shift and shiftindex cannot both be given')
+            if shiftscale is True:
+                self.__shift = miller.vector_crystal_to_cartesian(shift, self.rcell.box)
+            else:
+                self.__shift = np.asarray(shift)
+                assert self.__shift.shape == (3,)
+
+        elif shiftindex is not None:
+            self.__shift = self.shifts[shiftindex]
+
+        else:
+            self.__shift = self.shifts[0]

atomman/source/atomman/defect/GRIP.py

@@ -0,0 +1,545 @@
+from typing import Optional
+import secrets
+
+import numpy as np
+
+from .. import System
+from . import GrainBoundary
+from . import interstitial_site_finder
+
+from yabadaba.record import Record
+
+class GRIP(Record):
+    """
+    Class for managing input settings and building grain boundary
+    configurations according to the GRIP algorithm.
+    """
+
+    ########################## Basic metadata fields ##########################
+
+    @property
+    def style(self) -> str:
+        """str: The record style"""
+        return 'grip'
+
+    @property
+    def modelroot(self) -> str:
+        """str: The root element of the content"""
+        return 'grip'
+
+    ####################### Define Values and attributes #######################
+
+    def _init_values(self):
+        """
+        Method that defines the value objects for the Record.  This should
+        call the super of this method, then use self._add_value to create new Value objects.
+        Note that the order values are defined matters
+        when build_model is called!!!
+        """
+        # Shift input settings
+        self._add_value('float', 'shift_delta', defaultvalue=0.05,
+                        modelpath='input-parameter.shift.delta',
+                        description=' '.join([
+                            'The spacing to use between possible shift samples.',
+                            'Default value is 0.05. Note shifts should range',
+                            'from 0 to 1.']))
+
+        # Temperature input settings
+        self._add_value('float', 'temperature_min', defaultvalue=0,
+                        modelpath='input-parameter.temperature.min',
+                        description=' '.join([
+                            'The minimum temperature to include in the sampling.']))
+        self._add_value('float', 'temperature_max', defaultvalue=2000,
+                        modelpath='input-parameter.temperature.max',
+                        description=' '.join([
+                            'The maximum temperature to include in the sampling.']))
+        self._add_value('float', 'temperature_delta', defaultvalue=100,
+                        modelpath='input-parameter.temperature.delta',
+                        description=' '.join([
+                            'The spacing to use between possible temperature',
+                            'samples.  Default value is 100.']))
+        self._add_value('str', 'temperature_sample_style', defaultvalue='uniform',
+                        modelpath='input-parameter.temperature.sample_style',
+                        allowedvalues=['uniform'],
+                        description=' '.join([
+                            'The sampling style to use for the temperature.',
+                            '"uniform" will uniformly sample from the range provided',
+                            'and is the only currently supported style.']))
+        
+        # Sizemults input settings
+        self._add_value('int', 'sizemults_max1', defaultvalue=3,
+                        modelpath='input-parameter.sizemults.max1',
+                        description=' '.join([
+                            'The maximum size multiplier to use for the first in-plane',
+                            'box vector. The selected sample will be between 1 and this',
+                            'value inclusively. Default value is 3.']))
+        self._add_value('int', 'sizemults_max2', defaultvalue=3,
+                        modelpath='input-parameter.sizemults.max2',
+                        description=' '.join([
+                            'The maximum size multiplier to use for the second in-plane',
+                            'box vector. The selected sample will be between 1 and this',
+                            'value inclusively. Default value is 3.']))
+        self._add_value('str', 'sizemults_sample_style',
+                        modelpath='input-parameter.sizemults.sample_style',
+                        defaultvalue='exponential',
+                        allowedvalues=['uniform', 'exponential'],
+                        description=' '.join([
+                            'Indicates the sample style to use for the sizemults.',
+                            '"exponential" (default) will place higher sample weights',
+                            'on smaller sizemults. "uniform" will equally sample from',
+                            'the sizemults range.']))
+        
+        # Runsteps input settings
+        self._add_value('float', 'runsteps_chance', defaultvalue=0.95,
+                        modelpath='input-parameter.runsteps.chance',
+                        description=' '.join([
+                            'A probability rate between 0 and 1 for if the MD relaxation',
+                            'will be performed: a value of 0 means MD is never done and',
+                            'a value of 1 means MD is always done.  Default value is',
+                            '0.95 (5% chance of no MD).']))
+        self._add_value('int', 'runsteps_min', defaultvalue=5000,
+                        modelpath='input-parameter.runsteps.min',
+                        description=' '.join([
+                            'The minimum runsteps value to include in the sampling.',
+                            'Default value is 5000.']))
+        self._add_value('int', 'runsteps_max', defaultvalue=500000,
+                        modelpath='input-parameter.runsteps.max',
+                        description=' '.join([
+                            'The maximum runsteps value to include in the sampling.',
+                            'Default value is 500000.']))
+        self._add_value('int', 'runsteps_delta', defaultvalue=1000,
+                        modelpath='input-parameter.runsteps.delta',
+                        description=' '.join([
+                            'The spacing to use between possible runsteps samples.',
+                            'Default value is 1000.']))
+        self._add_value('str', 'runsteps_sample_style',
+                        modelpath='input-parameter.runsteps.sample_style',
+                        defaultvalue='exponential',
+                        allowedvalues=['uniform', 'exponential'],
+                        description=' '.join([
+                            'The sampling style to use for the runsteps.',
+                            '"uniform" will uniformly sample from the range provided.',
+                            '"exponential" (default) will weight smaller runsteps as',
+                            'being more likely.']))
+        
+        # Grain boundary builder settings
+        self._add_value('int', 'maxmult', defaultvalue=10,
+                        modelpath='input-parameter.builder.maxmult',
+                        description=' '.join([
+                            'The maximum size multiplier to use in searching for',
+                            'correspondence between the in-plane vectors of both',
+                            'grains.  Both grains will be searched up to this max,'
+                            "so only one grain's multiplier is guaranteed to be",
+                            'maxmult or less.  Default value is 10.']))
+        self._add_value('float', 'minwidth', defaultvalue=30,
+                        modelpath='input-parameter.builder.minwidth',
+                        description=' '.join([
+                            'The minimum width for both grains perpendicular to',
+                            'the grain boundary.  Default value is 30.']))
+        
+        # Atom deletion settings
+        self._add_value('float', 'delete_min', defaultvalue=0.0,
+                        modelpath='input-parameter.delete.min',
+                        description=' '.join([
+                            'Minimum fraction of atoms to delete.  Default value is 0.0.']))
+        self._add_value('float', 'delete_max', defaultvalue=1.0,
+                        modelpath='input-parameter.delete.max',
+                        description=' '.join([
+                            'Maximum fraction of atoms to delete.  Default value is 1.0.']))
+
+        # Atom perturbation settings
+        self._add_value('float', 'perturb_width', defaultvalue=10,
+                        modelpath='input-parameter.perturb.width',
+                        description=' '.join([
+                            'The width from the grain boundary in each grain within which',
+                            'atoms will be perturbed.  Default value is 10.']))
+        self._add_value('float', 'perturb_max1', defaultvalue=0.3,
+                        modelpath='input-parameter.perturb.max1',
+                        description=' '.join([
+                            'The maximum atomic perturbations that will be applied to',
+                            'atoms in grain 1.  Default value is 0.3.']))
+        self._add_value('float', 'perturb_max2', defaultvalue=0.0,
+                        modelpath='input-parameter.perturb.max2',
+                        description=' '.join([
+                            'The maximum atomic perturbations that will be applied to',
+                            'atoms in grain 2.  Default value is 0.0.']))
+
+        # Interstitial site settings
+        self._add_value('int', 'interstitial_max_num', defaultvalue=2,
+                        modelpath='input-parameter.interstitial.max_num',
+                        description=' '.join([
+                            "Specifies the max number of interstitial sites to fill.",
+                            "Note that the actual max may be less if the number of",
+                            "atoms or the number of interstitial sites at the grain",
+                            "boundary are smaller.  Default value is 2."]))
+        self._add_value('float', 'interstitial_width', defaultvalue=1.5,
+                        modelpath='input-parameter.interstitial.width',
+                        description=' '.join([
+                            "Only interstitial sites within the interstitial_width",
+                            "distance from the grain boundary will be considered for",
+                            "filling, and only atoms within 2*interstitial_width from",
+                            "the grain boundary will be considered for moving."]))
+        self._add_value('str', 'interstitial_sample_style',
+                        modelpath='input-parameter.interstitial.sample_style',
+                        defaultvalue='uniform',
+                        allowedvalues=['uniform', 'volume'],
+                        description=' '.join([
+                            "The sampling weight to use for selection of the interstitial",
+                            "sites to fill.  If 'uniform' (default), all sites will have",
+                            "equal likelihood of being filled.  If 'volume', then the",
+                            "likelihood of sites being filled is weighted based on the",
+                            "site's volume."]))
+
+        # Generated calculation settings and metadata
+        self._add_value('int', 'randomseed',
+                        modelpath='calculation-parameter.randomseed',
+                        description="The random number generator seed.")
+        self._add_value('float', 'shift1',
+                        modelpath='calculation-parameter.shift1',
+                        description="The relative shift along the first in-plane box vector.")
+        self._add_value('float', 'shift2',
+                        modelpath='calculation-parameter.shift2',
+                        description="The relative shift along the second in-plane box vector.")
+        self._add_value('int', 'sizemult1',
+                        modelpath='calculation-parameter.sizemult1',
+                        description="The size multiplier along the first in-plane box vector.")
+        self._add_value('int', 'sizemult2',
+                        modelpath='calculation-parameter.sizemult2',
+                        description="The size multiplier along the second in-plane box vector.")
+        self._add_value('int', 'runsteps',
+                        modelpath='calculation-parameter.runsteps',
+                        description="The number of MD relaxation steps to perform.")
+        self._add_value('float', 'temperature',
+                        modelpath='calculation-parameter.temperature',
+                        description="The temperature at which to perform the MD relaxation.")
+        self._add_value('float', 'density',
+                        modelpath='calculation-parameter.density',
+                        description="The atomic density of the grain boundary after atom deletion.")
+        self._add_value('int', 'ninterstitials',
+                        modelpath='calculation-parameter.ninterstitials',
+                        description="The number of interstitial positions filled.")
+
+    @property
+    def defaultname(self) -> Optional[str]:
+        """str: The name to default to, usually based on other properties"""
+        return 'grip-settings'
+
+    def boundary(self,
+                 grainboundary: GrainBoundary,
+                 randomseed: Optional[int] = None,
+                 decimals: int = 6,
+                 verbose: bool = False,
+                 **kwargs):
+        
+        # Update any calculation input settings if provided
+        if len(kwargs) > 0:
+            self.set_values(**kwargs)
+
+        # Set the random number seed and create a generator
+        if randomseed is None:
+            randomseed = secrets.randbits(32)
+        self.randomseed = randomseed
+        rng = np.random.default_rng(seed=randomseed)
+
+        # Select random input values
+        self.__set_shifts(rng, verbose)
+        self.__set_sizemults(rng, verbose)
+        self.__set_runsteps(rng, verbose)
+        self.__set_temperature(rng, verbose)
+        
+        # Build and modify the grain boundary system
+        system, natoms1 = self.__build_boundary(grainboundary, verbose)
+        system, natoms1 = self.__delete_atoms(system, natoms1, rng,
+                                              grainboundary, decimals, verbose)
+        self.__perturb_atoms(system, natoms1, rng, grainboundary, verbose)
+        self.__interstitial_atoms(system, rng, grainboundary, verbose)
+
+        return system, natoms1
+
+    def __set_shifts(self,
+                     rng: np.random.Generator,
+                     verbose: bool):
+        """
+        Selects the two in-plane vector shifts to apply to the system using
+        random uniform samples.
+        """
+        # Build array of possible shifts to sample from 
+        possibleshifts = np.arange(0, 1, self.shift_delta)
+
+        # Select gb shifts uniformly from possible values
+        self.shift1 = rng.choice(possibleshifts)
+        self.shift2 = rng.choice(possibleshifts)
+        
+        if verbose:
+            print('shift1:', self.shift1)
+            print('shift2:', self.shift2)
+
+    def __set_sizemults(self,
+                        rng: np.random.Generator,
+                        verbose: bool):
+        """
+        Selects random sizemults values for the two in-plane box vectors.
+        """
+        # Build array of all possible sizemults
+        sizemults1 = np.arange(1, self.sizemults_max1 + 1)
+        sizemults2 = np.arange(1, self.sizemults_max2 + 1)
+
+        if self.sizemults_sample_style == 'uniform':
+            # Uniformly sample from allowed values
+            self.sizemult1 = rng.choice(sizemults1)
+            self.sizemult2 = rng.choice(sizemults2)
+
+        elif self.sizemults_sample_style == 'exponential':
+            # Place higher weights on smaller systems
+            sizemultsweights1 = np.exp(-sizemults1) / np.sum(np.exp(-sizemults1))
+            sizemultsweights2 = np.exp(-sizemults2) / np.sum(np.exp(-sizemults2))
+        
+            # Select samples using the weights
+            self.sizemult1 = rng.choice(sizemults1, p=sizemultsweights1)
+            self.sizemult2 = rng.choice(sizemults2, p=sizemultsweights2)
+    
+        else:
+            raise ValueError('Unsupported sizemults_sample_style value')
+        
+        if verbose:
+            print('sizemult1:', self.sizemult1)
+            print('sizemult2:', self.sizemult2, flush=True)
+
+    def __set_runsteps(self,
+                       rng: np.random.Generator,
+                       verbose: bool):
+        """
+        Select a random number of runsteps and temperature for performing the
+        MD relaxation.
+        """
+        
+        if rng.random() > self.runsteps_chance:
+            # Skip MD run if probability check fails 
+            self.runsteps = 0
+        
+        elif self.runsteps_sample_style == 'uniform':
+            # Uniformly sample the number of MD steps
+            self.runsteps = int(np.round(rng.choice(np.arange(self.runsteps_min, self.runsteps_max + 1, self.runsteps_delta))))
+        
+        elif self.runsteps_sample_style == 'exponential':
+            # Exponentially scale the number of MD steps
+            C = np.log(self.runsteps_max / self.runsteps_min)
+            self.runsteps = int(np.round(self.runsteps_min * np.exp(C * rng.random()) / self.runsteps_delta) * self.runsteps_delta)
+
+        else:
+            raise ValueError('Unsupported runsteps_sample_style value')
+        
+        if verbose:
+            print('runsteps:', self.runsteps, flush=True)
+    
+    def __set_temperature(self,
+                          rng: np.random.Generator,
+                          verbose: bool):
+        """
+        Select a random number of runsteps and temperature for performing the
+        MD relaxation.
+        """
+        if self.runsteps == 0:
+            self.temperature = 0.0
+
+        elif self.temperature_sample_style == 'uniform':
+            # Select a random uniform sample for the temperature
+            self.temperature = np.round(rng.choice(np.arange(self.temperature_min, self.temperature_max + 1, self.temperature_delta)))
+
+        else:
+            raise ValueError('Unsupported temperature_sample_style value')
+        
+        if verbose:
+            print('temperature:', self.temperature, flush=True)
+
+    def __build_boundary(self,
+                         gb: GrainBoundary,
+                         verbose: bool):
+        """
+        Builds the grain boundary system using the builder and the selected
+        sizemults and shifts.
+        """
+        mults1, mults2, strain = gb.identifymults(maxmult=self.maxmult,
+                                                  minwidth=self.minwidth,
+                                                  setvalues=False)
+        
+        # Multiply the in-plane sizemults by the GRIP values
+        i1 = 0
+        i2 = 2
+        if gb.cutboxvector == 'a':
+            i1 = 1
+        elif gb.cutboxvector == 'c':
+            i2 = 1
+        mults1[i1] *= self.sizemult1
+        mults2[i1] *= self.sizemult1
+        mults1[i2] *= self.sizemult2
+        mults2[i2] *= self.sizemult2
+
+        if verbose:
+            print('mults1:', mults1)
+            print('mults2:', mults2)
+
+        # Call super to generate the boundary system
+        system, natoms1 = gb.boundary(mults1=mults1, mults2=mults2,
+                                      freesurface=True, straintype='top',
+                                      shift1=self.shift1, shift2=self.shift2,
+                                      deleter=0.0)
+        
+        if verbose:
+            print('system width:', system.box.vects[gb.cutindex, gb.cutindex])
+            print('natoms (initial):', system.natoms, flush=True)
+
+        return system, natoms1
+        
+    def __delete_atoms(self,
+                       system: System,
+                       natoms1: int,
+                       rng: np.random.Generator,
+                       gb: GrainBoundary,
+                       decimals: int,
+                       verbose: bool):
+        """
+        Randomly selects atoms for deletion from the grain boundary.
+        """        
+        # GB plane region ranges from min coord in top grain to that plus dlat
+        dlat = gb.dlat(decimals) - 10**-decimals
+        mincoord = system.atoms.pos[:natoms1, gb.cutindex].min()
+        boundaryz = mincoord + dlat
+
+        # Identify and count gb plane atoms
+        inplane = np.where(system.atoms.pos[:natoms1, gb.cutindex] < boundaryz)[0]
+        natomsplane = len(inplane)
+        
+        # Pick a random number of atoms to delete
+        ndel = int(rng.integers(np.floor(natomsplane * (1 - self.delete_max)),
+                                np.ceil(natomsplane * (1 - self.delete_min)),
+                                endpoint=True))
+        
+        # Randomly select ndel atoms for deletion
+        todelete = rng.choice(inplane, size=ndel, replace=False)
+        keepindex = [x for i, x in enumerate(range(system.natoms)) if i not in todelete]
+        
+        if verbose:
+            print('# atoms being deleted:', ndel)
+            for index in todelete:
+                print('atom deleted at', system.atoms.pos[index])
+
+        # Delete the selected atoms
+        newsystem = system.atoms_ix[keepindex]
+        newnatoms1 = natoms1 - ndel
+        
+        # Compute the grain boundary atomic density
+        self.density = (natomsplane - ndel) / natomsplane
+
+        if verbose:
+            print('natoms (now):', newsystem.natoms)
+            print('gb density:', self.density, flush=True)
+
+        return newsystem, newnatoms1
+
+    def __perturb_atoms(self,
+                        system: System,
+                        natoms1: int,
+                        rng: np.random.Generator,
+                        gb: GrainBoundary,
+                        verbose: bool):
+        """
+        Randomly perturb atoms near the grain boundary.
+        """
+        # Split atomic positions by grain
+        pos1 = system.atoms.pos[:natoms1]
+        pos2 = system.atoms.pos[natoms1:]
+
+        # Perturb grain 1 atoms
+        mincoord = pos1[:, gb.cutindex].min()
+        boundary = mincoord + self.perturb_width
+        inboundary = pos1[:, gb.cutindex] < boundary
+        pos1[inboundary, :] += self.perturb_max1 * rng.random([np.sum(inboundary), 3])
+
+        # Perturb grain 2 atoms
+        maxcoord = pos2[:, gb.cutindex].max()
+        boundary = maxcoord - self.perturb_width
+        inboundary = pos2[:, gb.cutindex] > boundary
+        pos2[inboundary, :] += self.perturb_max2 * rng.random([np.sum(inboundary), 3])
+
+        # Join pos and update in system
+        system.pos = np.vstack([pos1, pos2])
+
+        if verbose:
+            print('atoms perturbed', flush=True)
+
+    def __interstitial_atoms(self,
+                             system: System,
+                             rng: np.random.Generator,
+                             gb: GrainBoundary,
+                             verbose: bool):
+        """
+        Randomly moves atoms near the grain boundary into interstitial sites.
+        This identifies both interstitial sites and atoms near the grain
+        boundary, then randomly selects a random number of atoms to move into
+        randomly selected interstitial sites.
+        """
+        # Quick return if max is 0
+        if self.interstitial_max_num <= 0:
+            return
+        
+        # Create slice of the atomic system around the grain boundary
+        search_width = 10 * self.interstitial_width
+        in_search = ((system.atoms.pos[:, gb.cutindex] > -search_width) &
+                     (system.atoms.pos[:, gb.cutindex] < search_width))
+        search_system = system.atoms_ix[in_search]
+
+        # Find interstitial sites from the search system
+        allsites = interstitial_site_finder(search_system)
+
+        # Filter out sites away from the grain boundary
+        sites = []
+        for site in allsites:
+            if (site.pos[gb.cutindex] > -self.interstitial_width and 
+                site.pos[gb.cutindex] <  self.interstitial_width):
+                sites.append(site)
+        all_site_ids = [i for i in range(len(sites))]
+
+        if verbose:
+            print('# total interstitial sites:', len(sites), flush=True)
+
+        # Find ids of atoms near the grain boundary
+        in_boundary = ((system.atoms.pos[:, gb.cutindex] > -2 * self.interstitial_width) &
+                       (system.atoms.pos[:, gb.cutindex] < 2 *  self.interstitial_width))
+        atom_ids = np.where(in_boundary)[0]
+
+        if verbose:
+            print('# atoms for interstitial shifts:', len(atom_ids))
+
+        # Select max number to move based on max_num, num atoms and num sites
+        max_num = min([self.interstitial_max_num, len(sites), len(atom_ids)])
+
+        # Pick a random number of atoms to move from 0 to max_num
+        nmove = int(rng.integers(0, max_num, endpoint=True))
+
+        if verbose:
+            print('# atoms being shifted:', nmove)
+
+        # Shuffle atom_ids and only select the first nmove
+        np.random.shuffle(atom_ids)
+        atom_ids = atom_ids[:nmove]
+
+        if self.interstitial_sample_style == 'uniform':
+            # Randomly select interstitial sites to fill with no weights
+            site_ids = rng.choice(all_site_ids, size=nmove, replace=False)
+        
+        elif self.interstitial_sample_style == 'volume':
+            # Randomly select interstitial sites to fill weighted towards large volumes
+            volumes = np.array([site.volume for site in sites])
+            weights = volumes / np.sum(volumes)
+            site_ids = rng.choice(all_site_ids, size=nmove, replace=False, weights=weights)
+
+        # Move atoms to the interstitial sites
+        for atom_id, site_id in zip(atom_ids, site_ids):
+            if verbose:
+                print('atom at', system.atoms.pos[atom_id])
+                print('moved to', sites[site_id].pos, flush=True)
+            system.atoms.pos[atom_id] = sites[site_id].pos
+
+        self.ninterstitials = nmove
+        

atomman/source/atomman/defect/GammaSurface.py

@@ -0,0 +1,1366 @@
+# coding: utf-8
+# Standard Python imports
+from collections import OrderedDict
+import io
+from typing import Optional, Tuple, Union
+
+# http://pandas.pydata.org/
+import pandas as pd
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://www.scipy.org/
+from scipy.interpolate import Rbf, NearestNDInterpolator
+
+# http://matplotlib.org/
+import matplotlib.pyplot as plt
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# atomman imports
+from .. import Box
+from .. import unitconvert as uc
+from ..tools import miller
+from ..mep import create_path, BasePath
+
+class GammaSurface(object):
+    """
+    Class for representing gamma surfaces, i.e., generalized stacking faults.
+    """
+    
+    def __init__(self,
+                 model: Union[str, io.IOBase, DM, None] = None,
+                 a1vect: Optional[npt.ArrayLike] = None,
+                 a2vect: Optional[npt.ArrayLike] = None,
+                 a1: Optional[npt.ArrayLike] = None,
+                 a2: Optional[npt.ArrayLike] = None,
+                 E_gsf: Optional[npt.ArrayLike] = None,
+                 box: Optional[Box] = None,
+                 delta: Optional[npt.ArrayLike] = None):
+        """
+        Class initializer. Parameter model must be given alone. Otherwise,
+        all or none of a1vect, a2vect, a1, a2, and E_gsf must be given.
+        
+        Parameters
+        ----------
+        model : str, file-like object, DataModelDict, optional
+            XML/JSON data model containing the stacking fault information.
+        a1vect : array-like object, optional
+            The a1 shifting vector.  If box is given, a1vect is taken as a
+            crystal lattice vector, otherwise as a Cartesian vector.
+        a2vect : array-like object, optional
+            The a2 shifting vector.  If box is given, a2vect is taken as a
+            crystal lattice vector, otherwise as a Cartesian vector.
+        a1 : array-like object, optional
+            List of fractional coordinates along a1vect corresponding to the
+            E_gsf (and delta) values.
+        a2 : array-like object, optional
+            List of fractional coordinates along a2vect corresponding to the
+            E_gsf (and delta) values.
+        E_gsf : array-like object, optional
+            List of generalized stacking fault energies for the positions
+            associated with the corresponding (a1, a2) fractional coordinates.
+        box : atomman.Box, optional
+            Defines unit cell box dimensions for conversion between crystal
+            lattice and Cartesian vectors.  If not given, will be set as a
+            square unit box, thus no conversion will occur (i.e. a1vect,
+            a2vect will be Cartesian).
+        delta : array-like object, optional
+            List of change in displacements normal to the fault plane for the
+            positions associated with the corresponding (a1, a2) fractional
+            coordinates.
+        """
+    
+        # Load model if given
+        if model is not None:
+            try:
+                assert box is None
+                assert a1vect is None
+                assert a2vect is None
+                assert a1 is None
+                assert a2 is None
+                assert E_gsf is None
+                assert delta is None
+            except:
+                raise TypeError('model cannot be given with any other parameter')
+            else:
+                self.model(model=model)
+        
+        # Set values if given
+        elif (a1 is not None or a2 is not None or E_gsf is not None
+              or a1vect is not None or a2vect is not None
+              or delta is not None or box is not None):
+            try:
+                assert a1vect is not None
+                assert a2vect is not None
+                assert a1 is not None
+                assert a2 is not None
+                assert E_gsf is not None
+            except:
+                raise TypeError('Defining data requires a1vect, a2vect, a1, a2 and E_gsf')
+            else:  
+                self.set(a1vect, a2vect, a1, a2, E_gsf,  box=box, delta=delta)
+        
+        # Set flag for no supplied data
+        else:
+            self.__hasdata = False
+    
+    @property
+    def data(self) -> pd.DataFrame:
+        """pandas.DataFrame : The raw data."""
+        if self.__hasdata:
+            return self.__data
+        else:
+            raise AttributeError('gamma surface data not set')
+          
+    @property
+    def a1vect(self) -> np.ndarray:
+        """numpy.ndarray : The a1 shifting vector."""
+        if self.__hasdata:
+            return self.__a1vect
+        else:
+            raise AttributeError('gamma surface data not set')
+    
+    @property
+    def a2vect(self) -> np.ndarray:
+        """numpy.ndarray : The a2 shifting vector."""
+        if self.__hasdata:
+            return self.__a2vect
+        else:
+            raise AttributeError('gamma surface data not set')
+    
+    @property
+    def planenormal(self) -> np.ndarray:
+        """numpy.ndarray : The Cartesian vector normal to the fault plane."""
+        if self.__hasdata:
+            return self.__planenormal
+        else:
+            raise AttributeError('gamma surface data not set')
+
+    @property
+    def box(self) -> Box:
+        """
+        atomman.Box : A unit cell box used for converting between
+                      crystal lattice and Cartesian vectors.
+        """
+        if self.__hasdata:
+            return self.__box
+        else:
+            raise AttributeError('gamma surface data not set')
+    
+    def set(self,
+            a1vect: npt.ArrayLike,
+            a2vect: npt.ArrayLike,
+            a1: npt.ArrayLike,
+            a2: npt.ArrayLike,
+            E_gsf: npt.ArrayLike,
+            box: Optional[Box] = None,
+            delta: Optional[npt.ArrayLike] = None):
+        """
+        Sets generalized stacking fault data.
+        
+        Parameters
+        ----------
+        a1vect : array-like object
+            The a1 shifting vector.  If box is given, a1vect is taken as a
+            crystal lattice vector, otherwise as a Cartesian vector.
+        a2vect : array-like object
+            The a2 shifting vector.  If box is given, a2vect is taken as a
+            crystal lattice vector, otherwise as a Cartesian vector.
+        a1 : array-like object
+            List of fractional coordinates along a1vect corresponding to the
+            E_gsf (and delta) values.
+        a2 : array-like object
+            List of fractional coordinates along a2vect corresponding to the
+            E_gsf (and delta) values.
+        E_gsf : array-like object
+            List of generalized stacking fault energies for the positions
+            associated with the corresponding (a1, a2) fractional coordinates.
+        box : atomman.Box, optional
+            Defines unit cell box dimensions for conversion between crystal
+            lattice and Cartesian vectors.  If not given, will be set as a
+            square unit box, thus no conversion will occur (i.e. a1vect,
+            a2vect will be Cartesian).
+        delta : array-like object, optional
+            List of change in displacements normal to the fault plane for the
+            positions associated with the corresponding (a1, a2) fractional
+            coordinates.
+        """
+        # Set a1vect
+        if isinstance(a1vect, str):
+            a1vect = a1vect.split()
+        a1vect = np.asarray(a1vect, dtype=float)
+        if a1vect.shape == (4,):
+            a1vect = miller.vector4to3(a1vect)
+        elif a1vect.shape != (3,):
+            raise ValueError('a1vect must be a 3D vector')
+        self.__a1vect = a1vect
+
+        # Set a2vect
+        if isinstance(a2vect, str):
+            a2vect = a2vect.split()
+        a2vect = np.asarray(a2vect, dtype=float)
+        if a2vect.shape == (4,):
+            a2vect = miller.vector4to3(a2vect)
+        elif a2vect.shape != (3,):
+            raise ValueError('a2vect must be a 3D vector')
+        self.__a2vect = a2vect
+
+        # Set box
+        if box is None:
+            box = Box()
+        if not isinstance(box, Box):
+            raise TypeError('box must be an atomman.Box')
+        self.__box = box
+
+        # Set plane normal
+        a1vect = np.dot(a1vect, box.vects)
+        a2vect = np.dot(a2vect, box.vects)
+        planenormal = np.cross(a1vect, a2vect)
+        self.__planenormal = planenormal / np.linalg.norm(planenormal)
+
+        # Set data
+        data = OrderedDict()
+        data['a1'] = a1
+        data['a2'] = a2
+        data['E_gsf'] = E_gsf
+        if delta is not None:
+            data['delta'] = delta
+        self.__data = pd.DataFrame(data)
+
+        # Fit
+        self.__hasdata = True
+        self.fit()        
+    
+    def fit(self):
+        """
+        Defines the interpolation functions from the raw data.
+        """
+        
+        # Ignore a1, a2=1.0 values if included
+        shortdata = self.data[~(np.isclose(self.data.a1, 1.0) | np.isclose(self.data.a2, 1.0))]
+        
+        # Create supercells of values
+        a1 = shortdata.a1
+        a2 = shortdata.a2
+        a1 = np.concatenate([a1-1, a1-1, a1-1, a1, a1, a1, a1+1, a1+1, a1+1])
+        a2 = np.concatenate([a2-1, a2, a2+1, a2-1, a2, a2+1, a2-1, a2, a2+1])
+
+        # Find values in 0-1 cell +- one point
+        ua1 = np.unique(a1)
+        ua2 = np.unique(a2)
+        a1min = ua1[np.where(np.isclose(ua1, 0.0))[0][0] - 1] - 1e-8
+        a1max = ua1[np.where(np.isclose(ua1, 1.0))[0][-1] + 1] + 1e-8
+        a2min = ua2[np.where(np.isclose(ua2, 0.0))[0][0] - 1] - 1e-8
+        a2max = ua2[np.where(np.isclose(ua2, 1.0))[0][-1] + 1] + 1e-8
+        ix = np.where((a1 >= a1min) & (a1 <= a1max) & (a2 >= a2min) & (a2 <= a2max))
+        
+        # Fit energy
+        E_gsf = np.concatenate([shortdata.E_gsf] * 9)
+        self.__E_gsf_fit = Rbf(a1[ix], a2[ix], E_gsf[ix])
+        self.__E_gsf_nearest = NearestNDInterpolator(np.array([a1[ix], a2[ix]]).T, E_gsf[ix])
+        
+        # Fit delta
+        if 'delta' in self.data:
+            delta = np.concatenate([shortdata.delta] * 9)
+            self.__delta_fit = Rbf(a1[ix], a2[ix], delta[ix])
+            self.__delta_nearest = NearestNDInterpolator(np.array([a1[ix], a2[ix]]).T, delta[ix])
+    
+    def model(self,
+              model: Union[str, io.IOBase, DM, None] = None,
+              length_unit: str = 'angstrom',
+              energyperarea_unit: str = 'mJ/m^2') -> Optional[DM]:
+        """
+        Return or set DataModelDict representation of the gamma surface.
+        
+        Parameters
+        ----------
+        model : str, file-like object or DataModelDict, optional
+            XML/JSON content to extract gamma surface energy from. If not
+            given, model content will be generated.
+        length_unit : str, optional
+            Units to report delta displacement values in when a new model is
+            generated. Default value is 'angstrom'.
+        energyperarea_unit : str, optional
+            Units to report fault energy values in when a new model is
+            generated.  Default value is 'mJ/m^2'.
+        
+        Returns
+        -------
+        DataModelDict
+            A dictionary containing the stacking fault data of the
+            GammaSurface object.  Returned if model is not given.
+        """
+        # Set values if model given
+        if model is not None:
+            model = DM(model).find('stacking-fault-map')
+            
+            # Read in box, a1vect and a2vect
+            box = Box(avect = model['box']['avect'],
+                      bvect = model['box']['bvect'],
+                      cvect = model['box']['cvect'])
+            
+            a1vect = model['shift-vector-1']
+            a2vect = model['shift-vector-2']
+            
+            # Read in stacking fault data
+            gsf = model.find('stacking-fault-relation')
+            
+            a1 = gsf['shift-vector-1-fraction']
+            a2 = gsf['shift-vector-2-fraction']
+            E_gsf = uc.value_unit(gsf['energy'])
+            try:
+                delta = uc.value_unit(gsf['plane-separation'])
+            except:
+                delta = None
+            self.set(a1vect, a2vect, a1, a2, E_gsf, box=box, delta=delta)
+        
+        # Generate model
+        else:
+            model = DM()
+            model['stacking-fault-map'] = sfm = DM()
+            sfm['box'] = DM()
+            sfm['box']['avect'] = list(self.box.avect)
+            sfm['box']['bvect'] = list(self.box.bvect)
+            sfm['box']['cvect'] = list(self.box.cvect)
+            sfm['shift-vector-1'] = list(self.a1vect)
+            sfm['shift-vector-2'] = list(self.a2vect)
+            sfm['stacking-fault-relation'] = sfr = DM()
+            sfr['shift-vector-1-fraction'] = list(self.data.a1)
+            sfr['shift-vector-2-fraction'] = list(self.data.a2)
+            sfr['energy'] = uc.model(self.data.E_gsf, energyperarea_unit)
+            if 'delta' in self.data:
+                sfr['plane-separation'] = uc.model(self.data.delta, length_unit)
+            
+            return model
+    
+    def a12_to_pos(self,
+                   a1: npt.ArrayLike,
+                   a2: npt.ArrayLike,
+                   a1vect: Optional[npt.ArrayLike] = None,
+                   a2vect: Optional[npt.ArrayLike] = None) -> np.ndarray:
+        """
+        Conversion function from normalized a1, a2 coordinates to Cartesian
+        positions.
+        
+        Parameters
+        ----------
+        a1 : array-like object
+            Fractional distance(s) along a1 vector.
+        a2 : array-like object
+            Fractional distance(s) along a2 vector.
+        a1vect : array-like object, optional
+            Crystal vector for the a1 vector.  Default value of None uses the
+            saved a1vect.
+        a2vect : array-like object, optional
+            Crystal vector for the a2 vector.  Default value of None uses the
+            saved a2vect.
+        
+        Returns
+        -------
+        np.array
+            3D Cartesian position vector(s).
+        """
+        # Handle a1vect and a2vect
+        if a1vect is None:
+            a1vect = self.a1vect
+        a1vect = np.asarray(a1vect)
+
+        if a2vect is None:
+            a2vect = self.a2vect
+        a2vect = np.asarray(a2vect)
+        
+        # Convert a1vect and a2vect from crystal to Cartesian coordinates
+        a1vect = np.dot(a1vect, self.box.vects)
+        a2vect = np.dot(a2vect, self.box.vects)
+        
+        # Transform a1, a2 to Cartesian pos
+        return np.outer(a1, a1vect) + np.outer(a2, a2vect)
+        
+    def pos_to_xy(self,
+                  pos: npt.ArrayLike,
+                  xvect: Optional[npt.ArrayLike] = None
+                  ) -> Union[Tuple[float, float],
+                             Tuple[np.ndarray, np.ndarray]]:
+        """
+        Conversion function from Cartesian positions to plotting x, y
+        coordinates.
+        
+        Parameters
+        ----------
+        pos: array-like object
+            3D Cartesian position vector(s).
+        xvect : array-like object, optional
+            Cartesian vector corresponding to the plotting x-axis. If None (default), this is
+            taken as the Cartesian of a1vect.
+        
+        Returns
+        -------
+        x : float or numpy.ndarray
+            Plotting x coordinate(s).
+        y : float or numpy.ndarray
+            Plotting y coordinate(s).
+        """
+        # Handle xvect
+        if xvect is None:
+            xvect = np.dot(self.a1vect, self.box.vects)
+        xvect = np.asarray(xvect)        
+        if not np.isclose(np.dot(xvect, self.planenormal), 0.0):
+            raise ValueError('xvect must be in plane defined by a1vect and a2vect')
+        
+        # Build transformation tensor
+        yvect = np.cross(self.planenormal, xvect)
+        transform = np.array([xvect, yvect, self.planenormal])
+        transform = (transform.T / np.linalg.norm(transform, axis=1)).T
+        
+        # Transform coordinates to x,y,z orientation
+        pos = transform.dot(pos.T).T
+        
+        # Return x, y coordinates
+        return pos[...,0], pos[...,1]
+    
+    def a12_to_xy(self,
+                  a1: npt.ArrayLike,
+                  a2: npt.ArrayLike,
+                  a1vect: Optional[npt.ArrayLike] = None,
+                  a2vect: Optional[npt.ArrayLike] = None,
+                  xvect: Optional[npt.ArrayLike] = None
+                  ) -> Union[Tuple[float, float],
+                             Tuple[np.ndarray, np.ndarray]]:
+        """
+        Conversion function from normalized a1, a2 coordinates to plotting x, y
+        coordinates.
+        
+        Parameters
+        ----------
+        a1 : array-like object
+            Fractional distance(s) along a1 vector.
+        a2 : array-like object
+            Fractional distance(s) along a2 vector.
+        a1vect : array-like object, optional
+            Crystal vector for the a1 vector.  Default value of None uses the
+            saved a1vect.
+        a2vect : array-like object, optional
+            Crystal vector for the a2 vector.  Default value of None uses the
+            saved a2vect.
+        xvect : array-like object, optional
+            Cartesian vector corresponding to the plotting x-axis. If None (default), this is
+            taken as the Cartesian of a1vect.
+        
+        Returns
+        -------
+        x : float or numpy.ndarray
+            Plotting x coordinate(s).
+        y : float or numpy.ndarray
+            Plotting y coordinate(s).
+        """
+        # Set xvect as given a1vect if needed
+        if a1vect is not None and xvect is None:
+            xvect = np.dot(a1vect, self.box.vects)
+        
+        # Transform from a1, a2 to pos
+        pos = self.a12_to_pos(a1, a2, a1vect=a1vect, a2vect=a2vect)
+
+        # Transform from pos to x, y
+        return self.pos_to_xy(pos, xvect=xvect)
+    
+    def pos_to_a12(self,
+                   pos: npt.ArrayLike,
+                   a1vect: Optional[npt.ArrayLike] = None,
+                   a2vect: Optional[npt.ArrayLike] = None
+                   ) -> Union[Tuple[float, float],
+                              Tuple[np.ndarray, np.ndarray]]:
+        """
+        Conversion function from Cartesian positions to normalized a1, a2
+        coordinates.
+        
+        Parameters
+        ----------
+        pos : array-like object
+            3D Cartesian position vector(s).
+        a1vect : array-like object, optional
+            Crystal vector for the a1 vector.  Default value of None uses the
+            saved a1vect.
+        a2vect : array-like object, optional
+            Crystal vector for the a2 vector.  Default value of None uses the
+            saved a2vect.
+
+        Returns
+        -------
+        a1 : float(s)
+            Fractional distance(s) along a1 vector.
+        a2 : float(s)
+            Fractional distance(s) along a2 vector.
+        """
+
+        # Handle a1vect and a2vect
+        if a1vect is None:
+            a1vect = self.a1vect
+        a1vect = np.asarray(a1vect)
+
+        if a2vect is None:
+            a2vect = self.a2vect
+        a2vect = np.asarray(a2vect)
+        
+        # Convert a1vect and a2vect from crystal to Cartesian coordinates
+        a1vect = np.dot(a1vect, self.box.vects)
+        a2vect = np.dot(a2vect, self.box.vects)
+        
+        # Solve for a1, a2, a3
+        a3vect = np.cross(a1vect, a2vect)
+        coeffs = np.array([a1vect, a2vect, a3vect]).T
+        if pos.ndim == 2:
+            coeffs = np.array([coeffs])
+            pos = pos.reshape(pos.shape + (1,))
+
+            a123 = np.linalg.solve(coeffs, pos).reshape(pos.shape[:-1])
+        else:
+            a123 = np.linalg.solve(coeffs, pos)
+
+        assert np.allclose(a123[...,2], 0.0, atol=1e-6), np.abs(a123[...,2]).max()
+
+        # Return a1, a2
+        return a123[...,0], a123[...,1]
+    
+    def xy_to_pos(self,
+                  x: npt.ArrayLike,
+                  y: npt.ArrayLike,
+                  xvect: Optional[npt.ArrayLike] = None) -> np.ndarray:
+        """
+        Conversion function from plotting x, y coordinates to Cartesian
+        positions.
+        
+        Parameters
+        ----------
+        x : array-like object
+            Plotting x coordinate(s).
+        y : array-like object
+            Plotting y coordinate(s).
+        xvect : array-like object, optional
+            Cartesian vector corresponding to the plotting x-axis. If None
+            (default), this is taken as the Cartesian of a1vect.
+        
+        Returns
+        -------
+        pos: np.array
+            3D Cartesian position vector(s).
+        """
+        # Assign default xvect if needed
+        if xvect is None:
+            xvect = np.dot(self.a1vect, self.box.vects)
+        xvect = np.asarray(xvect)
+        if not np.isclose(np.dot(xvect, self.planenormal), 0.0):
+            raise ValueError('xvect must be in plane defined by a1vect and a2vect')
+       
+        # Build transformation tensor
+        yvect = np.cross(self.planenormal, xvect)
+        transform = np.array([xvect, yvect, self.planenormal])
+        transform = (transform.T / np.linalg.norm(transform, axis=1)).T
+        transform = np.linalg.inv(transform)
+        
+        # Transform coords
+        pos = np.outer(x, [1,0,0]) + np.outer(y, [0,1,0])
+        pos = transform.dot(pos.T).T
+        
+        # Return Cartesian pos
+        return pos
+    
+    def xy_to_a12(self,
+                  x: npt.ArrayLike,
+                  y: npt.ArrayLike,
+                  a1vect: Optional[npt.ArrayLike] = None,
+                  a2vect: Optional[npt.ArrayLike] = None,
+                  xvect: Optional[npt.ArrayLike] = None
+                  ) -> Union[Tuple[float, float],
+                             Tuple[np.ndarray, np.ndarray]]:
+        """
+        Conversion function from plotting x, y coordinates to normalized a1, a2
+        coordinates.
+        
+        Parameters
+        ----------
+        x : array-like object
+            Plotting x coordinate(s).
+        y : array-like object
+            Plotting y coordinate(s).
+        a1vect : array-like object, optional
+            Crystal vector for the a1 vector.  Default value of None uses the
+            saved a1vect.
+        a2vect : array-like object, optional
+            Crystal vector for the a2 vector.  Default value of None uses the
+            saved a2vect.
+        xvect : array-like object, optional
+            Cartesian vector corresponding to the plotting x-axis. If None
+            (default), this is taken as the Cartesian of a1vect.
+        
+        Returns
+        -------
+        a1 : float(s)
+            Fractional distance(s) along a1 vector.
+        a2 : float(s)
+            Fractional distance(s) along a2 vector.
+        """
+        
+        # Set xvect to given a1vect if needed
+        if a1vect is not None and xvect is None:
+            xvect = np.dot(a1vect, self.box.vects)
+
+        # Convert x, y to pos    
+        pos = self.xy_to_pos(x, y, xvect=xvect)
+
+        # Convert pos to a1, a2
+        return self.pos_to_a12(pos, a1vect=a1vect, a2vect=a2vect)
+    
+    def E_gsf(self, **kwargs) -> Union[float, np.ndarray]:
+        """
+        Returns values for generalized stacking fault energy interpolated from
+        the raw data.  Values can be obtained relative to a1, a2 fractional
+        coordinates, x, y plotting coordinates, or pos Cartesian coordinates.
+        
+        Parameters
+        ----------
+        a1 : array-like object, optional
+            Fractional coordinate(s) along a1vect.
+        a2 : array-like object, optional
+            Fractional coordinate(s) along a2vect.
+        pos : array-like object, optional
+            3D Cartesian position vector(s).
+        x : array-like object, optional
+            Plotting x coordinate(s).
+        y : array-like object, optional
+            Plotting y coordinate(s).
+        a1vect : array-like object, optional
+            Vector for the a1 fractional coordinates.  Default value of None 
+            uses the saved a1vect.
+        a2vect : array-like object, optional
+            Vector for the a2 fractional coordinates.  Default value of None 
+            uses the saved a2vect.
+        xvect : array-like object, optional
+            Cartesian vector corresponding to the plotting x-axis. If None
+            (default), this is taken as the Cartesian of a1vect.
+        smooth : bool, optional
+            If True (default) the returned values are smoothed using a RBF fit.
+            If False, the closest measured values are returned.
+        
+        Returns
+        -------
+        float or np.ndarray
+            The generalized stacking fault energy value(s).
+        """
+        if not self.__hasdata:
+            raise AttributeError('gamma surface data not set')
+        
+        smooth = kwargs.pop('smooth', True)
+
+        # Convert x, y to a1, a2
+        if 'x' in kwargs:
+            x = kwargs.pop('x')
+            y = kwargs.pop('y')
+            a1vect = kwargs.pop('a1vect', None)
+            a2vect = kwargs.pop('a2vect', None)
+            xvect = kwargs.pop('xvect', None)
+            assert len(kwargs) == 0, 'Unknown/incompatible arguments given'
+            a1, a2 = self.xy_to_a12(x, y, a1vect=a1vect, a2vect=a2vect, xvect=xvect)
+        
+        # Convert pos to a1, a2
+        elif 'pos' in kwargs:
+            pos = kwargs.pop('pos')
+            a1vect = kwargs.pop('a1vect', None)
+            a2vect = kwargs.pop('a2vect', None)
+            assert len(kwargs) == 0, 'Unknown/incompatible arguments given'
+            a1, a2 = self.pos_to_a12(pos, a1vect=a1vect, a2vect=a2vect)
+        
+        # Get a1, a2 from kwargs
+        else:
+            a1 = np.array(kwargs.pop('a1'))
+            a2 = np.array(kwargs.pop('a2'))
+            a1vect = kwargs.pop('a1vect', None)
+            a2vect = kwargs.pop('a2vect', None)
+            assert len(kwargs) == 0, 'Unknown/incompatible arguments given'
+            if a1vect is not None or a2vect is not None:
+                shape = a1.shape
+                # Convert into pos using given a1vect, a2vect, then back into a1, a2
+                pos = self.a12_to_pos(a1, a2, a1vect=a1vect, a2vect=a2vect)
+                a1, a2 = self.pos_to_a12(pos)
+                a1 = a1.reshape(shape)
+                a2 = a2.reshape(shape)
+
+        # Return interpolated values
+        if smooth:
+            cushion = (1 - self.data.a1.max()) / 2
+    
+            # Wrap all a1, a2 values within [-cushion, 1.0 - cushion)
+            while np.any(a1 >= 1.0 - cushion): 
+                a1[a1 >= 1.0 - cushion] -= 1.0
+            while np.any(a1 < -cushion): 
+                a1[a1 < -cushion] += 1.0
+            while np.any(a2 >= 1.0 - cushion): 
+                a2[a2 >= 1.0 - cushion] -= 1.0
+            while np.any(a2 < -cushion): 
+                a2[a2 < -cushion] += 1.0
+            
+            # Compute weighting factors
+            def zone1(x):
+                return (x + cushion) / (2 * cushion)
+            def zone2(x):
+                return np.ones_like(x)
+            x = np.piecewise(a1, [a1 < cushion, a1>= cushion], [zone1, zone2])
+            y = np.piecewise(a2, [a2 < cushion, a2>= cushion], [zone1, zone2])
+            
+            # Linear smoothing across boundaries
+            return ( x * y * self.__E_gsf_fit(a1, a2)
+                + x * (1 - y) * self.__E_gsf_fit(a1, a2 + 1)
+                + (1 - x) * y * self.__E_gsf_fit(a1 + 1, a2)
+                + (1 - x) * (1 - y) * self.__E_gsf_fit(a1 + 1, a2 + 1))
+        
+        # Return nearest values
+        else:
+
+            # Wrap all values within 0.0 < a1, a2 < 1.0
+            while np.any(a1 > 1.0): 
+                a1[a1 > 1.0] -= 1.0
+            while np.any(a1 < 0.0): 
+                a1[a1 < 0.0] += 1.0
+            while np.any(a2 > 1.0): 
+                a2[a2 > 1.0] -= 1.0
+            while np.any(a2 < 0.0): 
+                a2[a2 < 0.0] += 1.0
+
+            return self.__E_gsf_nearest(np.array([a1.flatten(), a2.flatten()]).T).reshape(a1.shape)
+    
+    def delta(self, **kwargs) -> Union[float, np.ndarray]:
+        """
+        Returns values for generalized stacking fault relaxation distance
+        interpolated from the raw data.  Values can be obtained relative to
+        a1, a2 fractional coordinates, x, y plotting coordinates, or pos
+        Cartesian coordinates.
+        
+        Parameters
+        ----------
+        a1 : array-like object, optional
+            Fractional coordinate(s) along a1vect.
+        a2 : array-like object, optional
+            Fractional coordinate(s) along a2vect.
+        pos : array-like object, optional
+            3D Cartesian position vector(s).
+        x : array-like object, optional
+            Plotting x coordinate(s).
+        y : array-like object, optional
+            Plotting y coordinate(s).
+        a1vect : array-like object, optional
+            Vector for the a1 fractional coordinates.  Default value of None 
+            uses the saved a1vect.
+        a2vect : array-like object, optional
+            Vector for the a2 fractional coordinates.  Default value of None 
+            uses the saved a2vect.
+        xvect : array-like object, optional
+            Cartesian vector corresponding to the plotting x-axis. If None
+            (default), this is taken as the Cartesian of a1vect.
+        smooth : bool, optional
+            If True (default) the returned values are smoothed using a RBF fit.
+            If False, the closest measured values are returned.
+        
+        Returns
+        -------
+        float or np.ndarray
+            The generalized stacking fault planar shift value(s).
+        """
+        if not self.__hasdata:
+            raise AttributeError('gamma surface data not set')
+        if 'delta' not in self.data:
+            raise AttributeError('delta data not set')
+        
+        smooth = kwargs.pop('smooth', True)
+
+        # Convert x, y to a1, a2
+        if 'x' in kwargs:
+            x = kwargs.pop('x')
+            y = kwargs.pop('y')
+            a1vect = kwargs.pop('a1vect', None)
+            a2vect = kwargs.pop('a2vect', None)
+            xvect = kwargs.pop('xvect', None)
+            assert len(kwargs) == 0, 'Unknown/incompatible arguments given'
+            a1, a2 = self.xy_to_a12(x, y, a1vect=a1vect, a2vect=a2vect, xvect=xvect)
+        
+        # Convert pos to a1, a2
+        elif 'pos' in kwargs:
+            pos = kwargs.pop('pos')
+            a1vect = kwargs.pop('a1vect', None)
+            a2vect = kwargs.pop('a2vect', None)
+            assert len(kwargs) == 0, 'Unknown/incompatible arguments given'
+            a1, a2 = self.pos_to_a12(pos, a1vect=a1vect, a2vect=a2vect)
+        
+        # Get a1, a2 from kwargs
+        else:
+            a1 = np.array(kwargs.pop('a1'))
+            a2 = np.array(kwargs.pop('a2'))
+            a1vect = kwargs.pop('a1vect', None)
+            a2vect = kwargs.pop('a2vect', None)
+            assert len(kwargs) == 0, 'Unknown/incompatible arguments given'
+            if a1vect is not None or a2vect is not None:
+                shape = a1.shape               
+                # Convert into pos using given a1vect, a2vect, then back into a1, a2
+                pos = self.a12_to_pos(a1, a2, a1vect=a1vect, a2vect=a2vect)
+                a1, a2 = self.pos_to_a12(pos)
+                a1 = a1.reshape(shape)
+                a2 = a2.reshape(shape)
+        
+        # Wrap all values within 0.0 < a1, a2 < 1.0
+        while np.any(a1 > 1.0): 
+            a1[a1 > 1.0] -= 1.0
+        while np.any(a1 < 0.0): 
+            a1[a1 < 0.0] += 1.0
+        while np.any(a2 > 1.0): 
+            a2[a2 > 1.0] -= 1.0
+        while np.any(a2 < 0.0): 
+            a2[a2 < 0.0] += 1.0
+        
+        if smooth:
+            return self.__delta_fit(a1, a2)
+        else:
+            return self.__delta_nearest(np.array([a1.flatten(), a2.flatten()]).T).reshape(a1.shape)
+    
+    def E_gsf_surface_plot(self,
+                           normalize: bool = False,
+                           smooth: bool = True, 
+                           a1vect: Optional[npt.ArrayLike] = None,
+                           a2vect: Optional[npt.ArrayLike] = None,
+                           xvect: Optional[npt.ArrayLike] = None,
+                           length_unit: str = 'Å',
+                           energyperarea_unit: str = 'eV/Å^2',
+                           numx: int = 100,
+                           numy: int = 100,
+                           figsize: Optional[tuple] = None,
+                           **kwargs) -> plt.figure:
+        """
+        Creates a 2D surface plot from the stacking fault energy values.
+        
+        Parameters
+        ----------
+        normalize : bool, optional
+            Flag indicating if axes are Cartesian (False, default) or
+            normalized by a1, a2 vectors (True).
+        smooth : bool, optional
+            If True (default), then plot shows smooth interpolated values.
+            If False, plot shows nearest raw data values.
+        a1vect : np.array, optional
+            Crystal vector for the a1 vector to use for plotting.  Default
+            value of None uses the saved a1vect.
+        a2vect : np.array, optional
+            Crystal vector for the a2 vector to use for plotting.  Default
+            value of None uses the saved a2vect.
+        xvect : numpy.array, optional
+            Crystal vector to align with the plotting x-axis for 
+            non-normalized plots.  If not given, this is taken as the Cartesian
+            of a1vect.
+        length_unit : str, optional
+            The unit of length to display non-normalized axes values in.
+            Default value is 'Å'.
+        energyperarea_unit : str, optional
+            The unit of energy per area to display the stacking fault energies
+            in. Default value is 'eV/Å^2'.
+        numx : int, optional
+            The number of plotting points to use along the x-axis.  Default
+            value is 100.
+        numy : int, optional
+            The number of plotting points to use along the y-axis.  Default
+            value is 100.       
+        figsize : tuple or None, optional
+            The figure's x,y dimensions.  If None (default), the values are
+            scaled such that the x,y spacings are approximately equal, and the
+            larger of the two values is set to 10.
+        **kwargs : dict, optional
+            Additional keywords are passed into the underlying 
+            matplotlib.pyplot.pcolormesh(). This allows control of such things
+            like the colormap (cmap).
+            
+        Returns
+        -------
+        matplotlib.figure
+        """
+        if not self.__hasdata:
+            raise AttributeError('gamma surface data not set')
+
+        # Extract data
+        if a1vect is None:
+            a1vect = self.a1vect
+        a1vect = np.asarray(a1vect)
+        if a2vect is None:
+            a2vect = self.a2vect
+        a2vect = np.asarray(a2vect)
+
+        # Generate grids of a1, a2 values from numx, numy
+        xvals = np.linspace(0, 1, numx)
+        yvals = np.linspace(0, 1, numy)
+        x_grid, y_grid = np.meshgrid(xvals, yvals)
+        x_gridc, y_gridc = np.meshgrid(xvals[:-1], yvals[:-1])
+        
+        # Generate grid of values either with or without interpolation
+        C = self.E_gsf(a1=x_gridc, a2=y_gridc, a1vect=a1vect, a2vect=a2vect, smooth=smooth)
+        
+        # Convert units of C using energyperarea_unit
+        C = uc.get_in_units(C, energyperarea_unit)
+        
+        # Set parameters for normalized plots
+        if normalize is True:
+            yscale = 1
+            xlabel = f'$a_1$ = {a1vect}'
+            ylabel = f'$a_2$ = {a2vect}'
+        
+        # Set parameters for absolute plots
+        else:
+            shape = x_grid.shape
+            x_grid, y_grid = self.a12_to_xy(x_grid.flatten(), y_grid.flatten(),
+                                            a1vect=a1vect, a2vect=a2vect, xvect=xvect)
+            x_grid.shape = shape
+            y_grid.shape = shape
+            x_grid = uc.get_in_units(x_grid, length_unit)
+            y_grid = uc.get_in_units(y_grid, length_unit)
+            yscale = (y_grid.max()-y_grid.min()) / (x_grid.max() - x_grid.min())
+            xlabel = f'$x$ along {a1vect} (${length_unit}$)'
+            ylabel = f'$y$ along {a2vect} (${length_unit}$)'
+        
+        # Set default figsize if needed
+        if figsize is None:
+            xscale = 1.175
+            if yscale < 1:
+                figsize = (xscale * 10, 10 * yscale)
+            else:
+                figsize = (xscale * 10 / yscale, 10)
+        
+        # Generate plot
+        fig = plt.figure(figsize=figsize)
+        plt.pcolormesh(x_grid, y_grid, C, **kwargs)
+        plt.xlabel(xlabel, fontsize='xx-large')
+        plt.ylabel(ylabel, fontsize='xx-large')
+        cbar = plt.colorbar(aspect=40, fraction=0.1)
+        cbar.ax.set_ylabel(f'$γ_{{gsf}}$ (${energyperarea_unit}$)', fontsize='x-large')
+        
+        return fig
+    
+    def E_gsf_line_plot(self,
+                        vect: Optional[npt.ArrayLike] = None,
+                        num: int = None,
+                        smooth: bool = True,
+                        length_unit: str = 'Å',
+                        energyperarea_unit: str = 'eV/Å^2',
+                        figsize: Optional[tuple] = None,
+                        fig: Optional[plt.figure] = None,
+                        **kwargs) -> plt.figure:
+        """
+        Generates a line plot for the interpolated generalized stacking fault
+        energy along a specified crystallographic vector in the (a1, a2) plane.
+        
+        Parameters
+        ----------
+        vect : numpy.array, optional
+            Vector to plot the gsf along.  If box is set, this vect will be a
+            lattice vector, otherwise it will be a Cartesian vector.  Must be 
+            in the plane defined by the GammaSurface object's a1vect and 
+            a2vect vectors.  Default value will use the set a1vect.
+        num : int, optional
+            The number of points to evaluate the generalized stacking fault
+            energy for.  Default value is 100 if smooth is True, otherwise is
+            number of unique a1 values from 0 to 1.
+        smooth : bool, optional
+            If True (default), then plot shows smooth interpolated values.
+            If False, plot shows nearest raw data values.
+        length_unit : str, optional
+            The unit of length to display the x-axis coordinates in.
+            Default value is 'Å'.
+        energyperarea_unit : str, optional
+            The unit of energy per area to display the stacking fault energies
+            in. Default value is 'eV/Å^2'.
+        figsize : tuple, optional
+            The x,y size of the figure to return.  Default value is (10, 6).
+        fig : matplotlib.figure, optional
+            An existing figure object to add the new plot to.  If not given, a
+            new figure is generated.
+        **kwargs : dict, optional
+            Additional keywords are passed into the underlying 
+            matplotlib.pyplot.plot(). This allows control of such things
+            like line color, style, etc.
+        
+        Returns
+        -------
+        matplotlib.figure
+        """
+        if not self.__hasdata:
+            raise AttributeError('gamma surface data not set')
+
+        if num is None:
+            if smooth:
+                num = 100
+            else:
+                unique_a1 = np.unique([self.data.a1 - 1, self.data.a1, self.data.a1 + 1])
+                num = len(unique_a1[(unique_a1 >=-0.000001) & (unique_a1 <=1.000001)])
+        
+        # Generate coordinates
+        a1 = np.linspace(0, 1, num)
+        a2 = np.zeros(num)
+        pos = self.a12_to_pos(a1, a2, a1vect=vect)
+        
+        # Evaluate interpolated energy and distance along x
+        E = uc.get_in_units(self.E_gsf(pos=pos, smooth=smooth), energyperarea_unit)
+        x = uc.get_in_units(np.linalg.norm(pos, axis=1), length_unit)
+        
+        # Create plot
+        xmax = x.max()
+        emin = E.min() * 1.05
+        emax = E.max() * 1.05
+        if fig is None:
+            if figsize is None:
+                figsize = (10, 6)
+            fig = plt.figure(figsize=figsize)
+        else:
+            old_xmax = fig.axes[0].get_xlim()[-1]
+            old_emin = fig.axes[0].get_ylim()[0]
+            old_emax = fig.axes[0].get_ylim()[-1]
+            if old_xmax > xmax:
+                xmax = old_xmax
+            if old_emin < emin:
+                emin = old_emin
+            if old_emax > emax:
+                emax = old_emax
+        if 'fmt' in kwargs:
+            fmt = kwargs.pop('fmt')      
+            plt.plot(x, E, fmt, **kwargs)
+        else:
+            plt.plot(x, E, **kwargs)
+        
+        if vect is None:
+            vect = self.a1vect
+
+        plt.xlabel(f'$x$ along {vect} (${length_unit}$)', fontsize='x-large')
+        plt.ylabel(f'$γ_{{gsf}}$ (${energyperarea_unit}$)', fontsize='x-large')
+        plt.xlim(0, xmax)
+        plt.ylim(emin, emax)
+        
+        return fig
+    
+    def delta_surface_plot(self,
+                           normalize: bool = False,
+                           smooth: bool = True, 
+                           a1vect: Optional[npt.ArrayLike] = None,
+                           a2vect: Optional[npt.ArrayLike] = None,
+                           xvect: Optional[npt.ArrayLike] = None,
+                           length_unit: str = 'Å',
+                           numx: int = 100,
+                           numy: int = 100,
+                           figsize: Optional[tuple] = None,
+                           **kwargs) -> plt.figure:
+        """
+        Creates a 2D surface plot from the delta planar displacement values.
+        
+        Parameters
+        ----------
+        normalize : bool, optional
+            Flag indicating if axes are Cartesian (False, default) or
+            normalized by a1, a2 vectors (True).
+        smooth : bool, optional
+            If True (default), then plot shows smooth interpolated values.
+            If False, plot shows nearest raw data values.
+        a1vect : np.array, optional
+            Crystal vector for the a1 vector to use for plotting.  Default
+            value of None uses the saved a1vect.
+        a2vect : np.array, optional
+            Crystal vector for the a2 vector to use for plotting.  Default
+            value of None uses the saved a2vect.
+        xvect : numpy.array, optional
+            Crystal vector to align with the plotting x-axis for 
+            non-normalized plots.  If not given, this is taken as the Cartesian
+            of a1vect.
+        length_unit : str, optional
+            The unit of length to display delta and non-normalized axes values
+            in.  Default value is 'Å'.
+        numx : int, optional
+            The number of plotting points to use along the x-axis.  Default
+            value is 100.
+        numy : int, optional
+            The number of plotting points to use along the y-axis.  Default
+            value is 100.       
+        figsize : tuple or None, optional
+            The figure's x,y dimensions.  If None (default), the values are
+            scaled such that the x,y spacings are approximately equal, and the
+            larger of the two values is set to 10.
+        **kwargs : dict, optional
+            Additional keywords are passed into the underlying 
+            matplotlib.pyplot.pcolormesh(). This allows control of such things
+            like the colormap (cmap).
+            
+        Returns
+        -------
+        matplotlib.figure
+        """
+        if not self.__hasdata:
+            raise AttributeError('gamma surface data not set')
+        if 'delta' not in self.data:
+            raise AttributeError('delta data not set')
+
+        # Extract data
+        if a1vect is None:
+            a1vect = self.a1vect
+        a1vect = np.asarray(a1vect)
+        if a2vect is None:
+            a2vect = self.a2vect
+        a2vect = np.asarray(a2vect)
+
+        # Generate grids of a1, a2 values from numx, numy
+        x_grid, y_grid = np.meshgrid(np.linspace(0, 1, numx),
+                                     np.linspace(0, 1, numy))
+        
+        # Generate grid of values either with or without interpolation
+        C = self.delta(a1=x_grid, a2=y_grid, a1vect=a1vect, a2vect=a2vect, smooth=smooth)
+        
+        # Convert units of C using length_unit
+        C = uc.get_in_units(C, length_unit)
+        
+        # Set parameters for normalized plots
+        if normalize is True:
+            yscale = 1
+            xlabel = f'$a_1$ = {a1vect}'
+            ylabel = f'$a_2$ = {a2vect}'
+        
+        # Set parameters for absolute plots
+        else:
+            shape = x_grid.shape
+            x_grid, y_grid = self.a12_to_xy(x_grid.flatten(), y_grid.flatten(),
+                                            a1vect=a1vect, a2vect=a2vect, xvect=xvect)
+            x_grid.shape = shape
+            y_grid.shape = shape
+            x_grid = uc.get_in_units(x_grid, length_unit)
+            y_grid = uc.get_in_units(y_grid, length_unit)
+            yscale = (y_grid.max()-y_grid.min()) / (x_grid.max() - x_grid.min())
+            xlabel = f'x (${length_unit}$)'
+            ylabel = f'y (${length_unit}$)'
+        
+        # Set default figsize if needed
+        if figsize is None:
+            xscale = 1.175
+            if yscale < 1:
+                figsize = (xscale * 10, 10 * yscale)
+            else:
+                figsize = (xscale * 10 / yscale, 10)
+        
+        # Generate plot
+        fig = plt.figure(figsize=figsize)
+        plt.pcolormesh(x_grid, y_grid, C, **kwargs)
+        plt.xlabel(xlabel, fontsize='x-large')
+        plt.ylabel(ylabel, fontsize='x-large')
+        cbar = plt.colorbar(aspect=40, fraction=0.1)
+        cbar.ax.set_ylabel(f'$δ_{{gsf}}$ (${length_unit}$)', fontsize='x-large')
+        
+        return fig
+    
+    def delta_line_plot(self,
+                        vect: Optional[npt.ArrayLike] = None,
+                        num: Optional[int] = None,
+                        smooth: bool = True,
+                        length_unit: str = 'Å',
+                        figsize: Optional[tuple] = None,
+                        fig: Optional[plt.figure] = None,
+                        **kwargs) -> plt.figure:
+        """
+        Generates a line plot for the interpolated delta planar shift values
+        along a specified crystallographic vector in the (a1, a2) plane.
+        
+        Parameters
+        ----------
+        vect : numpy.array, optional
+            Vector to plot the gsf along.  If box is set, this vect will be a
+            lattice vector, otherwise it will be a Cartesian vector.  Must be 
+            in the plane defined by the GammaSurface object's a1vect and 
+            a2vect vectors.  Default value will use the set a1vect.
+        num : int, optional
+            The number of points to evaluate the generalized stacking fault
+            energy for.  Default value is 100 if smooth is True, otherwise is
+            number of unique a1 values from 0 to 1.
+        smooth : bool, optional
+            If True (default), then plot shows smooth interpolated values.
+            If False, plot shows nearest raw data values.
+        length_unit : str, optional
+            The unit of length to display the x-axis coordinates in.
+            Default value is 'Å'.
+        figsize : tuple, optional
+            The x,y size of the figure to return.  Default value is (10, 6).
+        fig : matplotlib.figure, optional
+            An existing figure object to add the new plot to.  If not given, a
+            new figure is generated.
+        **kwargs : dict, optional
+            Additional keywords are passed into the underlying 
+            matplotlib.pyplot.plot(). This allows control of such things
+            like line color, style, etc.
+        
+        Returns
+        -------
+        matplotlib.figure
+        """
+        if not self.__hasdata:
+            raise AttributeError('gamma surface data not set')
+        if 'delta' not in self.data:
+            raise AttributeError('delta data not set')
+
+        if num is None:
+            if smooth:
+                num = 100
+            else:
+                unique_a1 = np.unique([self.data.a1-1, self.data.a1, self.data.a1+1])
+                num = len(unique_a1[(unique_a1 >=-0.000001) & (unique_a1 <=1.000001)])
+
+        # Generate coordinates
+        a1 = np.linspace(0, 1, num)
+        a2 = np.zeros(num)
+        pos = self.a12_to_pos(a1, a2, a1vect=vect)
+        
+        # Evaluate interpolated distance along x
+        d = uc.get_in_units(self.delta(pos=pos, smooth=smooth), length_unit)
+        x = uc.get_in_units(np.linalg.norm(pos, axis=1), length_unit)
+        
+        # Create plot
+        xmax = x.max()
+        dmin = d.min() * 1.05
+        dmax = d.max() * 1.05
+        if fig is None:
+            if figsize is None:
+                figsize = (10, 6)
+            fig = plt.figure(figsize=figsize)
+        else:
+            old_xmax = fig.axes[0].get_xlim()[-1]
+            old_dmin = fig.axes[0].get_ylim()[0]
+            old_dmax = fig.axes[0].get_ylim()[-1]
+            if old_xmax > xmax:
+                xmax = old_xmax
+            if old_dmin < dmin:
+                dmin = old_dmin
+            if old_dmax > dmax:
+                dmax = old_dmax
+        if 'fmt' in kwargs:
+            fmt = kwargs.pop('fmt')
+            plt.plot(x, d, fmt, **kwargs)
+        else:
+            plt.plot(x, d, **kwargs)
+        
+        if vect is None:
+            vect = self.a1vect
+
+        plt.xlabel(f'$x$ along {vect} (${length_unit}$)', fontsize='x-large')
+        plt.ylabel(f'$δ_{{gsf}}$ (${length_unit}$)', fontsize='x-large')
+        plt.xlim(0, xmax)
+        plt.ylim(dmin, dmax)
+        
+        return fig
+
+    def path(self,
+             coord: npt.ArrayLike,
+             style: str = 'ISM',
+             gradientfxn: str = 'cdiff',
+             gradientkwargs: Optional[dict] = None,
+             integratorfxn: str ='rk') -> BasePath:
+        """
+        Creates an mep Path object mapping for the gamma surface based on
+        supplied xy coordinates along the path line.
+        
+        Parameters
+        ----------
+        coord : array-like object
+            The xy coordinates of the points along the path.
+        style : str
+            The path/relaxer style to use.  Default value of 'ISM' will use improved string method.
+        gradientfxn : function, optional
+            The function to use to estimate the gradient of the energy.  Default
+            value of 'cdiff' will use atomman.mep.gradient.central_difference
+        gradientkwargs : dict or None, optional
+            The keyword arguments (i.e. settings) to use with the gradientfxn.
+            Default value of None will use {'shift':1e-7}.
+        integratorfxn : str or function, optional
+            The function to use to integrate relaxation steps.  Default value of
+            'rk' will use atomman.mep.integrator.rungekutta.
+            
+        Returns
+        -------
+        subclass of atomman.mep.BasePath
+            Specific class dictated by style: style=='ISM' -> ISMPath (only style currently).    
+        """
+        # Handle default values
+        if gradientkwargs is None:
+            gradientkwargs = {'shift':1e-7}
+        
+        # Define energyfxn for the path
+        def energyfxn(xy):
+            return self.E_gsf(x=xy[..., 0], y=xy[..., 1])
+
+        return create_path(coord, energyfxn, style=style, gradientfxn=gradientfxn,
+                           gradientkwargs=gradientkwargs, integratorfxn=integratorfxn)
+
+    def build_path(self,
+                   pos: npt.ArrayLike,
+                   npoints: int = 31,
+                   style: str = 'ISM',
+                   gradientfxn: str = 'cdiff',
+                   gradientkwargs: Optional[dict] = None,
+                   integratorfxn: str = 'rk') -> BasePath:
+        """
+        Builds a subclass of atomman.mep.BasePath as one or two line segments
+        along a gamma surface. The energy function along the path will be
+        properly set using E_gsf.
+        
+        Parameters
+        ----------
+        pos : array-like object
+            2x3 or 3x3 array of Miller vector points that defines the end points of the path's
+            line segment(s).
+        npoints : int, optional
+            The number of points to include along the path. Must be odd if three pos are used.
+            Default value is 31.
+        style : str
+            The path/relaxer style to use.  Default value of 'ISM' will use improved string method.
+        gradientfxn : function, optional
+            The function to use to estimate the gradient of the energy.  Default
+            value of 'cdiff' will use atomman.mep.gradient.central_difference
+        gradientkwargs : dict or None, optional
+            The keyword arguments (i.e. settings) to use with the gradientfxn.
+            Default value of None will use {'shift':1e-7}.
+        integratorfxn : str or function, optional
+            The function to use to integrate relaxation steps.  Default value of
+            'rk' will use atomman.mep.integrator.rungekutta.
+            
+        Returns
+        -------
+        subclass of atomman.mep.BasePath
+            Specific class dictated by style: style=='ISM' -> ISMPath (only style currently).    
+        """
+        
+        # Define path coordinate builder
+        def build_coord(startpos, endpos, npoints):
+
+            box = self.box
+            x, y = self.pos_to_xy(miller.vector_crystal_to_cartesian(startpos, box))
+            start_xy = np.array([x, y])
+
+            x, y = self.pos_to_xy(miller.vector_crystal_to_cartesian(endpos, box))
+            end_xy = np.array([x, y])
+
+            return np.vstack([np.linspace(start_xy[0], end_xy[0], npoints),
+                              np.linspace(start_xy[1], end_xy[1], npoints)]).T
+        
+        # Construct single segment path coordinates
+        if len(pos) == 2:
+            coord = build_coord(pos[0], pos[1], npoints)
+        
+        # Construct double segment path coordinates
+        elif len(pos) == 3:
+            assert npoints % 2 == 1, 'npoints must be odd'
+            npoints_2 = int(npoints + 1 / 2)
+            coorda = build_coord(pos[0], pos[1], npoints_2)
+            coordb = build_coord(pos[1], pos[2], npoints_2)
+            coord = np.vstack([coorda, coordb[1:]])
+            
+        else:
+            raise ValueError('pos must have 2 or 3 coordinates')
+        
+        return self.path(coord, style=style, gradientfxn=gradientfxn,
+                        gradientkwargs=gradientkwargs, integratorfxn=integratorfxn)
+    

atomman/source/atomman/defect/GrainBoundary.py

@@ -0,0 +1,236 @@
+# coding: utf-8
+# Standard Python imports
+from typing import Optional, Tuple
+
+from scipy.spatial.transform import Rotation
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+from DataModelDict import DataModelDict as DM
+
+# Local imports
+from .Boundary import Boundary
+from .TiltGrainBoundaryHelper import TiltGrainBoundaryHelper
+from .. import System, Box
+from ..tools import approx_rational
+from ..library.record.GrainBoundary import GrainBoundary as GBRecord
+
+
+class GrainBoundary(Boundary):
+    """
+    Class for generating systems to investigate grain boundaries. In comparison
+    to the more generic Boundary class, GrainBoundary only accepts one unit cell,
+    it limits configurations to zero-strain states, and it includes extra methods
+    and attributes specific to grain boundary configurations.
+    """
+
+    def __init__(self,
+                 ucell: System,
+                 uvws1,
+                 uvws2,
+                 conventional_setting: str = 'p',
+                 cutboxvector='c',
+                 maxmult: int = 10):
+        """
+        Initialize a grain boundary configuration.
+
+        Parameters
+        ----------
+        ucell : atomman.System
+            The reference unit cell to use for both grains.
+        uvws1 : array-like object
+            The three Miller(-Bravais) crystal vectors of ucell to use for
+            orienting the first grain such that each crystal vector will be
+            aligned with one of the box vectors of the final configuration.
+        uvws2 : array-like object
+            The three Miller(-Bravais) crystal vectors of ucell to use for
+            orienting the second grain such that each crystal vector will be
+            aligned with one of the box vectors of the final configuration.
+        conventional_setting : str, optional
+            Specifies which conventional lattice setting that ucell is in.
+            The default value of 'p' takes ucell to be primitive, in which case
+            the uvws1 and uvws2 values must be integers.  This must be specified
+            in order to access non-integer lattice vectors for the uvws. 
+        cutboxvector : str, optional
+            Indicates which of the three box vectors that the boundary will
+            be placed along. Default value is 'c'.
+        maxmult : int, optional
+            The max integer multiplier to use for the zero strain check.
+        """
+        # Call Boundary's init using the single ucell
+        super().__init__(ucell, ucell, uvws1, uvws2, 
+                         conventional_setting1=conventional_setting,
+                         conventional_setting2=conventional_setting,
+                         cutboxvector=cutboxvector,
+                         zerostrain=True, maxmult=maxmult)
+        
+        # Find the transformation for rcell1 to rcell2
+        rvects1 = self.transform_p1_to_r1.apply(self.ucell.box.vects)
+        rvects2 = self.transform_p2_to_r2.apply(self.ucell.box.vects)
+        self.transform = np.linalg.lstsq(rvects1, rvects2, rcond=None)[0].T
+        self.__transform_r1_to_r2 = Rotation.from_matrix(np.linalg.lstsq(rvects1, rvects2, rcond=None)[0].T)
+
+    @classmethod
+    def from_model(cls,
+                   ucell: System,
+                   record: GBRecord,
+                   maxmult: int = 10):
+        """
+        Allows for the grain boundary settings to be loaded from a grain_boundary
+        record rather than manually specifying the inputs.
+
+        Parameters
+        ----------
+        ucell : atomman.System
+            The reference unit cell to use for both grains.
+        record : str, path, DataModelDict.DataModelDict or atomman.library.record.GrainBoundary
+            A grain_boundary-style record containing the input settings to load.
+            Can be given as a file path, str file contents, DataModelDict contents,
+            or a GrainBoundary record object.
+        maxmult : int, optional
+            The max integer multiplier to use for the zero strain check.
+        
+        Returns
+        -------
+        atomman.defect.GrainBoundary
+        """
+        # Extract inputs from the grain_boundary record
+        if not isinstance(record, GBRecord):
+            record = GBRecord(model = record)
+        obj = cls(ucell, maxmult=maxmult, **record.parameters)
+
+        return obj
+
+    @classmethod
+    def symmetric_tilt(cls,
+                       ucell: System,
+                       axis_uvw: npt.ArrayLike,
+                       plane1_hkl: Optional[npt.ArrayLike] = None,
+                       in1_uvw: Optional[npt.ArrayLike] = None,
+                       conventional_setting: str = 'p',
+                       ref_hkl: Optional[npt.ArrayLike] = None,
+                       ref_uvw: Optional[npt.ArrayLike] = None,
+                       cutboxvector: str = 'c',
+                       maxindex: int = 20,
+                       maxmult: int = 10,
+                       tol: float = 1e-8):
+        """
+        Initialize for symmetric tilt grain boundary configurations.
+
+        Parameters
+        ----------
+        ucell : atomman.System
+            The unit cell to use for both top and bottom grains.
+        axis_uvw : array-like
+            The Miller [uvw] or Miller-Bravais [uvtw] crystal vector of ucell
+            that serves as the tilt axis.  The tilt axis is a common vector in
+            the grain boundary plane that is shared by both grains.
+        in1_uvw : array-like object
+            The first grain's in-plane vector given as a Miller or
+            Miller-Bravais crystal vector.
+        ref_uvw : array-like object or None, optional
+            A reference in-plane vector that when crossed with the tilt axis
+            identifies the grain boundary plane associated with the 0 degree
+            misorientation configuration.  If given, in2 is found such
+            that the two grain boundary planes have the same angle wrt the
+            reference plane.  If None (default), then in2 is selected based on
+            producing the smallest misorientation angle, which usually but not
+            always corresponds to a symmetric tilt boundary.
+        cutboxvector : str, optional
+            Sets the alignment of the uvws to the final configuration's box
+            vectors by specifying which of the box vectors is out-of-plane
+            with respect to the grain boundary plane. Default value is 'c',
+            which aligns the tilt axis with a, and in1 (and in2) with b.
+        maxindex : int, optional
+            The maximum absolute vector index to search over for the u,v,w
+            values: u, v, and w can all independently vary from
+            -maxindex to maxindex.  Default value is 20.
+        maxmult : int, optional
+            The max integer multiplier to use for the zero strain check if
+            zerostrain is True.
+        tol : float, optional
+            A floating point tolerance used in finding the compatible primitive
+            unit cell.  Available as a parameter in case issues are encountered.
+            Default value is 1e-8.
+        
+        Returns
+        -------
+        atomman.defect.GrainBoundary
+        """
+        # Initialize helper
+        helper = TiltGrainBoundaryHelper(ucell, axis_uvw,
+                                         conventional_setting=conventional_setting,
+                                         ref_uvw=ref_uvw, ref_hkl=ref_hkl, tol=tol)
+
+        # Identify rotation uvws
+        uvws1, uvws2 = helper.symmetric_uvws(plane1_hkl=plane1_hkl, in1_uvw=in1_uvw,
+                                            cutboxvector=cutboxvector,
+                                            maxindex=maxindex)
+        obj = cls(ucell, uvws1, uvws2, conventional_setting=conventional_setting,
+                  cutboxvector=cutboxvector)
+
+        return obj
+
+    @property
+    def ucell(self) -> System:
+        """atomman.System: The conventional reference unit cell for both grains. Alias for ucell1 and ucell2"""
+        return self.ucell1
+
+    @property
+    def ucell_prim(self) -> System:
+        """atomman.System: The primitive reference unit cell for both grains. Alias for ucell_prim1 and ucell_prim2"""
+        return self.ucell_prim1
+    
+    @property
+    def transform_r1_to_r2(self) -> Rotation:
+        """scipy.spatial.transform.Rotation: The Cartesian rotation associated with rcell1 to rcell2"""
+        return self.__transform_r1_to_r2
+    
+    @property
+    def misorientation(self) -> float:
+        """float : The misorientation angle for the grain boundary"""
+        return np.linalg.norm(self.transform_r1_to_r2.as_rotvec(degrees=True))
+    
+    def sigma(self,
+              tol: float = 1e-6) -> int:
+        """Compute the sigma factor for the grain boundary"""
+
+        t1 = self.transform_r1_to_r2.as_matrix()
+        t2 = self.transform_r1_to_r2.inv().as_matrix()
+
+        denominators = approx_rational(np.vstack([t1, t2]).flatten(), tol=tol)[1]
+
+        # Sigma is the least common multiplier of the denominators
+        return np.lcm.reduce(denominators)
+    
+    def dlat(self,
+             precision: int = 6) -> float:
+        """
+        Computes the lattice thickness for the grain boundary by building a
+        lattice system for the primitive cell and finding the distance between
+        atoms perpendicular to the grain boundary plane.
+        
+        Parameters
+        ----------
+        precision : int, optional
+            The rounding precision to use in identifying unique atom
+            coordinates.  Default value is 6.
+
+        Returns
+        -------
+        float
+            The distance between two lattice atom positions in the direction
+            perpendicular to the grain boundary plane.
+        """
+        # Construct a lattice system from the primitive unit cell and 1 atom
+        latticesystem = System(box=Box(vects=self.ucell_prim.box.vects))
+        
+        # Rotate and supersize
+        testsystem = latticesystem.rotate(self.uvws_prim1).supersize(2, 2, 2)
+        
+        # Find the difference between the two nearest atom positions perpendicular to the cut
+        unique_z = sorted(list(set(testsystem.atoms.pos[:, self.cutindex].round(precision))))
+        return unique_z[1] - unique_z[0]
+    

atomman/source/atomman/defect/InterstitialSite.py

@@ -0,0 +1,168 @@
+from copy import deepcopy
+
+from scipy.spatial import Voronoi, ConvexHull
+
+import numpy as np
+
+from .. import Atoms
+
+class InterstitialSite():
+    
+    def __init__(self,
+                 pos: np.ndarray,
+                 neighbor_atoms: Atoms):
+        """
+        Initializes an InterstitialSite object
+        
+        Parameters
+        ----------
+        pos : numpy.ndarray
+            The coordinates for the interstitial position
+        neighbor_pos : numpy.ndarray
+            The coordinates for the atoms that neighbor the interstitial.
+            These should correspond to either direct or replica atoms from
+            the source atomic system.        
+        """
+        self.__pos = pos
+        self.__neighbor_atoms = neighbor_atoms
+    
+    def __eq__(self, other):
+        """
+        Compare InterstitialSites using is_similar() with the default settings.
+        """
+        return self.is_similar(other)
+        
+        
+    def is_similar(self,
+                   other,
+                   decimals: int = 6,
+                   use_dmag: bool = False) -> bool:
+        """
+        Compares agains another InterstitialSite based on the neighbor atoms'
+        atype and dvect or dmag values.
+        
+        
+        Parameters
+        ----------
+        other : InterstitialSite
+            The other InterstitialSite to compare against.
+        decimals : int, optional
+            The number of decimal points to round the dvect or dmag values to
+            before comparing.  Default value is 6.
+        use_dmag : bool
+            If True then the comparison will use atype and dmag.  If False
+            (default) then the comparison will use atype and dvect.  Roughly,
+            this means that setting this to True will perform a rotation
+            invariant comparison while leaving it False will not.
+        """
+        # First check number of atoms
+        if self.neighbor_atoms.natoms != other.neighbor_atoms.natoms:
+            return False
+        
+        atype0 = self.neighbor_atoms.atype
+        atype1 = other.neighbor_atoms.atype
+
+        if use_dmag:
+            # Extract and round dmag values
+            d0 = np.round(self.neighbor_dmag, decimals=decimals)
+            d1 = np.round(other.neighbor_dmag, decimals=decimals)
+        
+            # Get sorting indices
+            sorted_indices0 = np.lexsort((d0, atype0))
+            sorted_indices1 = np.lexsort((d1, atype1))
+            
+        else:
+            # Extract and round dvect values
+            d0 = np.round(self.neighbor_dvect, decimals=decimals)
+            d1 = np.round(other.neighbor_dvect, decimals=decimals)
+        
+            # Get sorting indices
+            sorted_indices0 = np.lexsort((d0[:, 2], d0[:, 1], d0[:, 0], atype0))
+            sorted_indices1 = np.lexsort((d1[:, 2], d1[:, 1], d1[:, 0], atype1))
+        
+        # Sort the arrays
+        atype0 = atype0[sorted_indices0]
+        atype1 = atype1[sorted_indices1]
+        d0 = d0[sorted_indices0]
+        d1 = d1[sorted_indices1]
+            
+        # Compare
+        return np.allclose(atype0, atype1) and np.allclose(d0, d1)
+        
+    @property
+    def pos(self):
+        return self.__pos
+    
+    @property
+    def neighbor_atoms(self):
+        return self.__neighbor_atoms
+    
+    @property
+    def volume(self):
+        return ConvexHull(self.neighbor_atoms.pos).volume
+    
+    @property
+    def neighbor_dvect(self):
+        return self.neighbor_atoms.pos - self.pos
+    
+    @property
+    def neighbor_dmag(self):
+        return np.linalg.norm(self.neighbor_dvect, axis=1)
+    
+    def is_strained(self, rtol=1e-05, atol=1e-08):
+        return not np.allclose(self.neighbor_dmag, self.neighbor_dmag[0])
+    
+    def asdict(self, rtol=1e-05, atol=1e-08):
+        d = {
+            'pos[0]': self.pos[0],
+            'pos[1]': self.pos[1],
+            'pos[2]': self.pos[2],
+            '#neighbors': self.neighbor_atoms.natoms,
+            'volume': self.volume,
+            'strained': self.is_strained(rtol=rtol, atol=atol)
+        }
+        return d
+    
+def interstitial_site_finder(system):
+    """
+    Generates a list of interstitial sites for an atomic configuration using
+    a Voronoi analysis.
+    
+    Parameters
+    ----------
+    system : atomman.System
+        The atomic configuration to search for interstitial sites.
+    
+    Returns
+    -------
+    list of atomman.defect.InterstitialSite
+        The identified interstitial sites.
+    """
+        
+    # Supersize the system in all directions 
+    bigsystem = system.supersize((-1,2), (-1,2), (-1,2))
+    
+    # Compute the Voronoi analysis
+    vor = Voronoi(bigsystem.atoms.pos)
+    
+    # Filter out the Voronoi vertices that are not in the middle replica
+    isin_ucell = system.box.inside(vor.vertices + .0005)
+    vertices_pos = vor.vertices[isin_ucell]
+    vertices_ids = np.where(isin_ucell)[0] # ids of vor.vertices that correspond to vertices
+    
+    # Initialize neighbors lists
+    neighborlists = [ [] for nix in range(np.sum(isin_ucell))]
+    
+    # Search for all atoms that neighbor the vertices
+    for atom_id, region_id in enumerate(vor.point_region):
+        region_vertices_ids = vor.regions[region_id]
+        for vertex_index, vertex_id in enumerate(vertices_ids):
+            if vertex_id in region_vertices_ids:
+                neighborlists[vertex_index].append(atom_id)
+                
+    interstitialsites = []
+    for vertex_pos, neighborlist in zip(vertices_pos, neighborlists):
+        neighbor_atoms = bigsystem.atoms[neighborlist]
+        interstitialsites.append(InterstitialSite(vertex_pos, neighbor_atoms))
+        
+    return interstitialsites

atomman/source/atomman/defect/IsotropicVolterraDislocation.py

@@ -0,0 +1,299 @@
+# coding: utf-8
+# Standard Python libraries
+import warnings
+from typing import Optional, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# atomman imports
+from . import VolterraDislocation
+from .. import Box, ElasticConstants
+
+class IsotropicVolterraDislocation(VolterraDislocation):
+    """
+    Class for representing the isotropic Volterra solution for a straight dislocation.
+    """
+
+    def solve(self,
+              C: ElasticConstants,
+              burgers: npt.ArrayLike,
+              ξ_uvw: Optional[npt.ArrayLike] = None,
+              slip_hkl: Optional[npt.ArrayLike] = None,
+              transform: Optional[npt.ArrayLike] = None,
+              axes: Optional[npt.ArrayLike] = None,
+              box: Optional[Box] = None,
+              m: Union[str, npt.ArrayLike] = 'x',
+              n: Union[str, npt.ArrayLike] = 'y',
+              cart_axes: bool = False,
+              tol: float = 1e-8):
+        """
+        Computes the elastic solution for an isotropic volterra dislocation.
+
+        Parameters
+        ----------
+        C : atomman.ElasticConstants
+            The medium's elastic constants.
+        burgers : array-like object
+            The dislocation's Burgers vector.
+        ξ_uvw : array-like object
+            The Miller crystal vector associated with the dislocation's line
+            direction.  Must be given with slip_hkl to identify the
+            transformation matrix to use on C and burgers.
+        slip_hkl : array-like object
+            The Miller plane indices associated with the dislocation's slip
+            plane.  Must be given with slip_hkl to identify the
+            transformation matrix to use on C and burgers.
+        transform : array-like object, optional
+            A 3x3 set of orthogonal Cartesian vectors that define the
+            transformation matrix to use on C and burgers to convert from the
+            standard (unit cell) and dislocation orientations.  The 3 vectors
+            will automatically be converted into unit vectors.  Using this is
+            an alternative to using ξ_uvw and slip_hkl.
+        axes : array-like object, optional
+            Same as transform.  Retained for backwards compatibility.
+        box : atomman.Box, optional
+            The unit cell's box that crystal vectors are taken with respect to.
+            If not given, will use a cubic box with a=1 meaning that burgers,
+            ξ_uvw and slip_hkl will be interpreted as Cartesian vectors.
+        m : str or array-like object, optional
+            The 3D Cartesian unit vector to align with the dislocation solution's m-axis,
+            i.e. the in-plane direction perpendicular to the dislocation line.  Also
+            accepts str values of 'x', 'y', or 'z', in which case the dislocation axis will
+            be aligned with the corresponding Cartesian axis.  Default value is 'x'.
+        n : str or array-like object, optional
+            The 3D Cartesian unit vector to align with the dislocation solution's n-axis,
+            i.e. the slip plane normal. Also accepts str values of 'x', 'y', or 'z', in
+            which case the dislocation axis will be aligned with the corresponding Cartesian
+            axis. Default value is 'y'.
+        cart_axes : bool, optional
+            Setting this to True will also perform an assertion check that the m- and n-axes
+            are both aligned with Cartesian axes. This is a requirement for some of the
+            atomic configuration generators. Default value is False as the elastic solution
+            by itself does not require the limitation.
+        tol : float
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        """
+        # Check that C is isotropic
+        if not C.is_normal('isotropic', atol=0.0, rtol=1e-4):
+            raise ValueError('C must be isotropic elastic constants')
+        C = C.normalized_as('isotropic')
+
+        VolterraDislocation.solve(self, C, burgers, ξ_uvw=ξ_uvw, slip_hkl=slip_hkl,
+                                  transform=transform, axes=axes, box=box,
+                                  m=m, n=n, cart_axes=cart_axes, tol=tol)
+
+        # Save shear modulus and Poissons ratio
+        bulk = self.C.bulk()
+        self.__mu = self.C.shear()
+        self.__nu = (3 * bulk - 2 * self.mu) / (2 * (3 * bulk + self.mu))
+
+    @property
+    def mu(self) -> float:
+        """float: The isotropic shear modulus"""
+        return self.__mu
+
+    @property
+    def nu(self) -> float:
+        """float: The isotropic Poisson's ratio"""
+        return self.__nu
+
+    @property
+    def K_tensor(self):
+        """numpy.ndarray : The energy coefficient tensor"""
+
+        # Construct K_tensor in standard setting
+        K_e = self.mu / (1 - self.nu)
+        K_s = self.mu
+        K = np.array([[K_e, 0.0, 0.0],
+                      [0.0, K_e, 0.0],
+                      [0.0, 0.0, K_s]])
+
+        # Transform tensor from m, n, ξ system
+        trans = np.array([self.m, self.n, self.ξ])
+        K = trans.T.dot(K.dot(trans))
+
+        # Round away near-zero terms
+        K[np.isclose(K / K.max(), 0.0, atol=self.tol)] = 0.0
+        return K
+
+    def theta(self, pos: npt.ArrayLike) -> np.ndarray:
+        """
+        Computes arctan(y / x) ranging from -π to π.
+
+        Parameters
+        ----------
+        pos : array-like object
+            3D vector position(s).
+
+        Returns
+        -------
+        numpy.ndarray
+            The theta angles for each 3D position.
+        """
+        pos = np.asarray(pos, dtype=float)
+        x = pos.dot(self.m)
+        y = pos.dot(self.n)
+
+        # Compute arctan(y/x) for all values
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            theta = np.arctan(y / x)
+
+        # Handle special cases and ensure value range -π to π
+        theta[(x == 0) & (y > 0)] = np.pi / 2
+        theta[(x == 0) & (y < 0)] = -np.pi / 2
+        theta[(x < 0)] += np.pi 
+        theta[(theta >= np.pi)] -= 2 * np.pi
+
+        return theta
+
+    def displacement(self, pos: npt.ArrayLike) -> np.ndarray:
+        """
+        Compute the position-dependent isotropic displacements.
+
+        Parameters
+        ----------
+        pos : array-like object
+            3D vector position(s).
+
+        Returns
+        -------
+        numpy.ndarray
+            The computed 3D vector displacements at all given points.
+        """
+        pos = np.asarray(pos)
+        if pos.shape == (3,):
+            pos = pos.reshape(1,3)
+
+        # Split pos, burgers into components
+        x = pos.dot(self.m)
+        y = pos.dot(self.n)
+        b_s = self.burgers.dot(self.ξ)
+        b_e = self.burgers.dot(self.m)
+        nu = self.nu
+
+        # Compute displacement components in m, n, ξ directions
+        disp_m = b_e / (2 * np.pi) * (self.theta(pos) + (x * y) / (2 * (1 - nu) * (x**2 + y**2)))
+
+        disp_n = b_e / (2 * np.pi) * (-(1 - 2 * nu) / (4 * (1 - nu)) * np.log(x**2 + y**2)
+                           + (y**2) / (2 * (1 - nu) * (x**2 + y**2)))
+
+        disp_ξ = b_s / (2 * np.pi) * (self.theta(pos))
+
+        # Combine into array
+        disp = np.outer(disp_ξ, self.ξ) + np.outer(disp_m, self.m) + np.outer(disp_n, self.n)
+
+        if disp.shape[0] == 1:
+            return disp[0]
+        else:
+            return disp
+
+    def strain(self, pos: npt.ArrayLike) -> np.ndarray:
+        """
+        Compute the position-dependent isotropic strains.  The equations used are derived
+        from ϵ_ij = S_ijkl σ_kl.
+
+        Parameters
+        ----------
+        pos : array-like object
+            3D vector position(s).
+
+        Returns
+        -------
+        numpy.ndarray
+            The computed 3x3 strain states at all given points.
+        """
+        pos = np.asarray(pos)
+        if pos.shape == (3,):
+            pos = pos.reshape(1,3)
+
+        # Split pos, burgers into components
+        x = pos.dot(self.m)
+        y = pos.dot(self.n)
+        b_s = self.burgers.dot(self.ξ)
+        b_e = self.burgers.dot(self.m)
+        nu = self.nu
+
+        # Initialize empty strain array
+        strain = np.empty(pos.shape[:-1] + (3,3))
+
+        # Strain components due to b_s
+        strain[..., 0, 2] = strain[..., 2, 0] = -b_s * y / (4 * np.pi * (x**2 + y**2))
+        strain[..., 1, 2] = strain[..., 2, 1] =  b_s * x / (4 * np.pi * (x**2 + y**2))
+
+        # Shear strain components due to b_e
+        strain[..., 0, 1] = strain[..., 1, 0] = b_e * (x * (x**2 - y**2)) / (4 * np.pi * (1 - nu) * (x**2 + y**2)**2)
+
+        # Normal strain components due to b_e
+        common = b_e * y / (4 * np.pi * (1 - nu**2) * (x**2 + y**2)**2)
+        strain[..., 0, 0] = common * (x**2 * (-3 - nu + 2 * nu**2) + y**2 * (-1 + nu + 2 * nu**2))
+        strain[..., 1, 1] = common * (x**2 * (1 + 3 * nu + 2 * nu**2) + y**2 * (-1 + nu + 2 * nu**2))
+
+        # Set zero values
+        strain[..., 2, 2] = 0.0
+
+        # Get the reverse transformation matrix
+        transform = np.array([self.m, self.n, self.ξ]).T
+
+        # Transform strains
+        strain = np.einsum('mi, nj, ...ij -> ...mn', transform, transform, strain)
+
+        if strain.shape[0] == 1:
+            return strain[0]
+        else:
+            return strain
+
+    def stress(self, pos: npt.ArrayLike) -> np.ndarray:
+        """
+        Compute the position-dependent isotropic stresses.
+
+        Parameters
+        ----------
+        pos : array-like object
+            3D vector position(s).
+
+        Returns
+        -------
+        numpy.ndarray
+            The computed 3x3 stress states at all given points.
+        """
+        pos = np.asarray(pos)
+        if pos.shape == (3,):
+            pos = pos.reshape(1,3)
+
+        # Split pos, burgers into components
+        x = pos.dot(self.m)
+        y = pos.dot(self.n)
+        b_s = self.burgers.dot(self.ξ)
+        b_e = self.burgers.dot(self.m)
+        nu = self.nu
+        mu = self.mu
+
+        # Initialize empty stress array
+        stress = np.empty(pos.shape[:-1] + (3,3))
+
+        # Stress components due to b_s
+        pre_s = mu * b_s / (2 * np.pi)
+        stress[..., 0, 2] = stress[..., 2, 0] =-pre_s * y / (x**2 + y**2)
+        stress[..., 1, 2] = stress[..., 2, 1] = pre_s * x / (x**2 + y**2)
+
+        # Stress components due to b_e
+        pre_e = mu * b_e / (2 * np.pi * (1 - nu))
+        stress[..., 0, 0] =-pre_e * (y * (3 * x**2 + y**2)) / (x**2 + y**2)**2
+        stress[..., 1, 1] = pre_e * (y * (x**2 - y**2)) / (x**2 + y**2)**2
+        stress[..., 2, 2] = nu * (stress[..., 0, 0] + stress[..., 1, 1])
+        stress[..., 0, 1] = stress[..., 1, 0] = pre_e * (x * (x**2 - y**2)) / (x**2 + y**2)**2
+
+        # Get the reverse transformation matrix
+        transform = np.array([self.m, self.n, self.ξ]).T
+
+        # Transform stresses
+        stress = np.einsum('mi, nj, ...ij -> ...mn', transform, transform, stress)
+
+        if stress.shape[0] == 1:
+            return stress[0]
+        else:
+            return stress

atomman/source/atomman/defect/SDVPN.py

@@ -0,0 +1,1243 @@
+# coding: utf-8
+
+# Standard Python libraries
+import io
+import warnings
+from typing import Optional, Tuple, Union
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+# https://www.scipy.org/
+from scipy.optimize import minimize, OptimizeResult
+
+# https://matplotlib.org/
+import matplotlib.pyplot as plt
+
+# https://github.com/usnistgov/DataModelDict
+from DataModelDict import DataModelDict as DM
+
+# atomman imports
+import atomman.unitconvert as uc
+from . import GammaSurface, VolterraDislocation
+
+class SDVPN(object):
+    """
+    Class representation of the semidiscrete variational Peierls-Nabarro
+    dislocation model.
+    """
+    
+    def __init__(self,
+                 volterra: Optional[VolterraDislocation] = None,
+                 gamma: Optional[GammaSurface] = None,
+                 model: Union[str, io.IOBase, DM, None] = None, 
+                 tau: npt.ArrayLike = np.zeros((3,3)),
+                 alpha: float = 0.0,
+                 beta: npt.ArrayLike = np.zeros((3,3)),
+                 cutofflongrange: Optional[float] = None,
+                 fullstress: bool = True,
+                 cdiffelastic: bool = False,
+                 cdiffsurface: bool = True,
+                 cdiffstress: bool = False,
+                 min_method: str = 'Powell',
+                 min_kwargs: Optional[dict] = None,
+                 min_options: Optional[dict] = None):
+        """
+        Initializes an SDVPN object.
+        
+        Parameters
+        ----------
+        volterra : atomman.defect.VolterraDislocation, optional
+            The elastic solution for a Volterra dislocation to use as the basis
+            of the model. Either volterra or model are required, and both cannot
+            be given at the same time.
+        gamma : atomman.defect.GammaSurface, optional
+            The gamma surface to use for the solution.  Required unless model
+            is given and the model content contains gamma surface data.
+        model : str or DataModelDict, optional
+            Saved data from previous SDVPN runs to load.  Either volterra or
+            model are required, and both cannot be given at the same time.
+        tau : numpy.ndarray, optional
+            A (3,3) array giving the stress tensor to apply to the system
+            using the stress energy term.  Only the xy, yy, and yz components
+            are used.  Default value is all zeros.
+        alpha : list of float, optional
+            The alpha coefficient(s) used by the nonlocal energy term.  Default
+            value is [0.0].
+        beta : numpy.ndarray, optional
+            The (3,3) array of beta coefficient(s) used by the surface energy
+            term.  Default value is all zeros.
+        cutofflongrange : float, optional
+            The cutoff distance to use for computing the long-range energy.
+            Default value is 1000 angstroms.
+        fullstress : bool, optional
+            Flag indicating which stress energy algorithm to use.  Default
+            value is True.
+        cdiffelastic : bool, optional
+            Flag indicating if the dislocation density for the elastic energy
+            component is computed with central difference (True) or simply
+            neighboring values (False).  Default value is False.
+        cdiffsurface : bool, optional
+            Flag indicating if the dislocation density for the surface energy
+            component is computed with central difference (True) or simply
+            neighboring values (False).  Default value is True.
+        cdiffstress : bool, optional
+            Flag indicating if the dislocation density for the stress energy
+            component is computed with central difference (True) or simply
+            neighboring values (False).  Only matters if fullstress is True.
+            Default value is False.
+        min_method : str, optional
+            The scipy.optimize.minimize method to use.  Default value is
+            'Powell'.
+        min_kwargs : dict, optional
+            Any keyword arguments to pass on to scipy.optimize.minimize besides
+            the coordinates, method and options.
+        min_options : dict, optional
+            Any options to pass on to scipy.optimize.minimize. Default value
+            is {}.
+        """
+        
+        # Load solution from existing model
+        if model is not None:
+            if volterra is not None:
+                raise ValueError('model cannot be given with volterra')
+            
+            self.load(model, gamma=gamma)
+        
+        # Extract parameters and check solution compatibility
+        elif volterra is not None:
+            
+            # Check that gamma is given
+            if gamma is None:
+                raise ValueError('gamma is required if volterra is given')
+            
+            # Check that burgers is in the slip plane
+            if not np.isclose(np.dot(volterra.n, volterra.burgers), 0.0):
+                raise ValueError('dislocation burgers vector must be in the slip plane')
+            
+            # Get m, n, ξ, K_tensor, burgers, and transform from volterra
+            m, n, ξ = volterra.m, volterra.n, volterra.ξ
+            K_tensor = volterra.K_tensor
+            burgers = volterra.burgers
+            transform = volterra.transform
+            
+            # Transform K_tensor, burgers and transform to [m,n,ξ] orientation
+            mnξ = np.array([m, n, ξ]) # This is transformation matrix to [m,n,ξ] setting
+            K_tensor = mnξ.dot(K_tensor.dot(mnξ.T))
+            burgers = mnξ.dot(burgers)
+            transform = np.matmul(mnξ, transform)
+            
+            # Check if dislocation system is compatible with gamma surface
+            planenormal = transform.dot(gamma.planenormal)
+            if not np.isclose(planenormal[0], 0.0) or not np.isclose(planenormal[2], 0.0):
+                raise ValueError('different slip planes for gamma and volterra found')
+
+            # Set basic solution definition
+            self.__K_tensor = K_tensor
+            self.__burgers = burgers
+            self.__transform = transform
+            self.__gamma = gamma
+
+            # Set options
+            self.tau = tau
+            self.alpha = alpha
+            self.beta = beta
+            if cutofflongrange is None:
+                self.cutofflongrange = uc.set_in_units(1000, 'angstrom')
+            else:
+                self.cutofflongrange = cutofflongrange
+            self.fullstress = fullstress
+            self.cdiffelastic = cdiffelastic
+            self.cdiffsurface = cdiffsurface
+            self.cdiffstress = cdiffstress
+            self.min_method = min_method
+            self.min_options = min_options
+            self.min_kwargs = min_kwargs
+
+        else:
+            raise ValueError('either dislsol or model must be given')
+    
+    @property
+    def x(self) -> np.ndarray:
+        """numpy.ndarray : The x coordinates."""
+        try:
+            return self.__x
+        except:
+            raise AttributeError('x values not set yet')
+    
+    @x.setter
+    def x(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype=float)
+        assert value.ndim == 1
+        diff = value[1:] - value[:-1]
+        assert np.allclose(diff[0], diff), 'x values must be evenly spaced'
+        assert diff[0] > 0, 'x values must be in increasing order'
+        self.__x = value
+
+    @property
+    def disregistry(self) -> np.ndarray:
+        """numpy.ndarray : The disregistry vector for each x coordinate."""
+        try:
+            return self.__disregistry
+        except:
+            raise AttributeError('disregistry values not set yet')
+
+    @disregistry.setter
+    def disregistry(self, value: npt.ArrayLike):
+        value = np.asarray(value)
+        assert value.ndim == 2 and value.shape[1] == 3, 'invalid disregistry dimensions'
+        assert np.allclose(value[:,1], 0.0), 'y (i.e. out-of-plane) component of disregistry not supported'
+        self.__disregistry = value
+
+    @property
+    def K_tensor(self) -> np.ndarray:
+        """numpy.ndarray : Dislocation energy coefficient tensor."""
+        return self.__K_tensor
+
+    @property
+    def burgers(self) -> np.ndarray:
+        """numpy.ndarray : Burgers vector."""
+        return self.__burgers
+        
+    @property
+    def transform(self) -> np.ndarray:
+        """numpy.ndarray : Transformation matrix from standard crystal setting to dislocation solution setting."""
+        return self.__transform
+    
+    @property
+    def gamma(self) -> GammaSurface:
+        """atomman.defect.GammaSurface : The stacking fault map."""
+        return self.__gamma
+    
+    @property
+    def tau(self) -> np.ndarray:
+        """numpy.ndarray : The applied 3x3 stress tensor."""
+        return self.__tau
+
+    @tau.setter
+    def tau(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype=float)
+        assert value.shape == (3,3)
+        self.__tau = value
+    
+    @property
+    def alpha(self) -> tuple:
+        """tuple of float : Coefficients for nonlocal energy correction."""
+        return self.__alpha
+    
+    @alpha.setter
+    def alpha(self, value: Union[float, tuple]):
+        try:
+            self.__alpha = tuple(value)
+        except:
+            self.__alpha = (value,)
+
+    @property
+    def beta(self) -> np.ndarray:
+        """numpy.ndarray : 3x3 coefficients for gradient energy correction."""
+        return self.__beta
+    
+    @beta.setter
+    def beta(self, value: npt.ArrayLike):
+        value = np.asarray(value, dtype=float)
+        assert value.shape == (3,3)
+        self.__beta = value
+
+    @property
+    def cutofflongrange(self) -> float:
+        """float : Cutoff distance for long-range elastic energy."""
+        return self.__cutofflongrange
+    
+    @cutofflongrange.setter
+    def cutofflongrange(self, value: float):
+        self.__cutofflongrange = float(value)
+
+    @property
+    def fullstress(self) -> bool:
+        """bool : Flag indicating which stress algorithm was used."""
+        return self.__fullstress
+
+    @fullstress.setter
+    def fullstress(self, value: bool):
+        assert isinstance(value, bool)
+        self.__fullstress = value
+    
+    @property
+    def cdiffelastic(self) -> bool:
+        """bool : Flag indicating if elastic energy used central difference for computing the dislocation density."""
+        return self.__cdiffelastic
+    
+    @cdiffelastic.setter
+    def cdiffelastic(self, value: bool):
+        assert isinstance(value, bool)
+        self.__cdiffelastic = value
+
+    @property
+    def cdiffsurface(self) -> bool:
+        """bool : Flag indicating if surface energy used central difference for computing the dislocation density."""
+        return self.__cdiffsurface
+    
+    @cdiffsurface.setter
+    def cdiffsurface(self, value: bool):
+        assert isinstance(value, bool)
+        self.__cdiffsurface = value
+
+    @property
+    def cdiffstress(self) -> bool:
+        """bool : Flag indicating if stress energy used central difference for computing the dislocation density."""
+        return self.__cdiffstress
+    
+    @cdiffstress.setter
+    def cdiffstress(self, value: bool):
+        assert isinstance(value, bool)
+        self.__cdiffstress = value
+
+    @property
+    def min_method(self) -> str:
+        """str : scipy.optimize.minimize method used."""
+        return self.__min_method
+    
+    @min_method.setter
+    def min_method(self, value: str):
+        self.__min_method = str(value)
+
+    @property
+    def min_options(self) -> dict:
+        """dict : scipy.optimize.minimize options used."""
+        return self.__min_options
+
+    @min_options.setter
+    def min_options(self, value: Optional[dict]):
+        if value is None:
+            self.__min_options = {}
+        elif isinstance(value, dict):
+            self.__min_options = value
+        else:
+            raise TypeError('min_options must be a dict')
+
+    @property
+    def min_kwargs(self) -> dict:
+        """dict : scipy.optimize.minimize keywords used."""
+        return self.__min_kwargs
+    
+    @min_kwargs.setter
+    def min_kwargs(self, value: Optional[dict]):
+        if value is None:
+            self.__min_kwargs = {}
+        elif isinstance(value, dict):
+            self.__min_kwargs = value
+        else:
+            raise TypeError('min_kwargs must be a dict')
+
+    @property
+    def res(self) -> OptimizeResult:
+        """OptimizeResult : scipy.optimize.minimize result."""
+        try:
+            return self.__res
+        except:
+            return None
+    
+    def solve(self,
+              x: Optional[npt.ArrayLike] = None,
+              disregistry: Optional[npt.ArrayLike] = None,
+              tau: Optional[npt.ArrayLike] = None,
+              alpha: Optional[list] = None,
+              beta: Optional[npt.ArrayLike] = None,
+              cutofflongrange: Optional[float] = None,
+              fullstress: Optional[bool] = None,
+              cdiffelastic: Optional[bool] = None,
+              cdiffsurface: Optional[bool] = None,
+              cdiffstress: Optional[bool] = None,
+              min_method: Optional[str] = None,
+              min_kwargs: Optional[dict] = None,
+              min_options: Optional[dict] = None):
+        """
+        Solves the semidiscrete variational Peierls-Nabarro dislocation
+        disregistry through energy minimization using the set class
+        properties.  All parameters are optional keyword arguments that
+        can be used to change any of the previous settings.
+        
+        Parameters
+        ----------
+        x : numpy.ndarray, optional
+            An array of shape (N) giving the x coordinates corresponding to
+            the disregistry solution.
+        disregistry : numpy.ndarray, optional
+            A (N,3) array giving the initial disregistry vector guess at each
+            x coordinate.
+        tau : numpy.ndarray, optional
+            A (3,3) array giving the stress tensor to apply to the system
+            using the stress energy term.  Only the xy, yy, and yz components
+            are used.
+        alpha : list of float, optional
+            The alpha coefficient(s) used by the nonlocal energy term.
+        beta : numpy.ndarray, optional
+            The (3,3) array of beta coefficient(s) used by the surface energy
+            term.
+        cutofflongrange : float, optional
+            The cutoff distance to use for computing the long-range energy.
+        fullstress : bool, optional
+            Flag indicating which stress energy algorithm to use.
+        cdiffelastic : bool, optional
+            Flag indicating if the dislocation density for the elastic energy
+            component is computed with central difference (True) or simply
+            neighboring values (False).
+        cdiffsurface : bool, optional
+            Flag indicating if the dislocation density for the surface energy
+            component is computed with central difference (True) or simply
+            neighboring values (False).
+        cdiffstress : bool, optional
+            Flag indicating if the dislocation density for the stress energy
+            component is computed with central difference (True) or simply
+            neighboring values (False).  Only matters if fullstress is True.
+        min_method : str, optional
+            The scipy.optimize.minimize method to use.
+        min_kwargs : dict, optional
+            Any keyword arguments to pass on to scipy.optimize.minimize besides
+            the coordinates, method and options.
+        min_options : dict, optional
+            Any options to pass on to scipy.optimize.minimize.
+        """
+
+        # Change attribute values if given
+        if x is not None:
+            self.x = x
+        if disregistry is not None:
+            self.disregistry = disregistry
+        if tau is not None:
+            self.tau = tau
+        if alpha is not None:
+            self.alpha = alpha
+        if beta is not None:
+            self.beta = beta
+        if cutofflongrange is not None:
+            self.cutofflongrange = cutofflongrange
+        if fullstress is not None:
+            self.fullstress = fullstress
+        if cdiffelastic is not None:
+            self.cdiffelastic = cdiffelastic
+        if cdiffsurface is not None:
+            self.cdiffsurface = cdiffsurface
+        if cdiffstress is not None:
+            self.cdiffstress = cdiffstress
+        if min_method is not None:
+            self.min_method = min_method
+        if min_options is not None:
+            self.min_options = min_options
+        if min_kwargs is not None:
+            self.min_kwargs = min_kwargs
+
+        # Check that x and disregistry exist and are of the same length
+        if len(self.x) != len(self.disregistry):
+            raise ValueError('x and disregistry are not of the same length')
+        
+        # Define subfunctions
+        def decompose(d):
+            """Breaks disregistry into components for minimization"""
+            d13 = np.concatenate([d[1:-1, 0], d[1:-1, 2]])
+            first = d[0]
+            last = d[-1]
+            return d13, first, last
+
+        def recompose(d13, first, last):
+            """Reassembles the disregistry components"""
+            half = int(len(d13)/2)
+            d = np.zeros((half+2, 3))
+            d[0] = first
+            d[-1] = last
+            d[1:-1, 0] = d13[:half]
+            d[1:-1, 2] = d13[half:]
+            return d
+
+        def min_func(d13, first, last):
+            """Function for minimizing"""
+            disregistry = recompose(d13, first, last)
+            return self.total_energy(disregistry=disregistry)
+        
+        # Solve disregistry
+        d13, first, last = decompose(self.disregistry)
+        res = minimize(min_func, d13, args=(first, last),
+                    method=self.min_method, options=self.min_options, **self.min_kwargs)
+        self.disregistry = recompose(res.x, first, last)
+
+        self.__res = res
+    
+    def disldensity(self,
+                    x: Optional[npt.ArrayLike] = None,
+                    disregistry: Optional[npt.ArrayLike] = None,
+                    cdiff: bool = False
+                    ) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Computes the dislocation density as the numerical derivative of
+        disregistry with respect to x.  Uses either neighboring values
+        
+            ρ[i] = (δ[i] - δ[i-1]) / (x[i] - x[i-1])
+        
+        or central difference
+        
+            ρ[i] = (δ[i+1] - δ[i-1]) / (x[i+1] - x[i-1])
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        cdiff : bool, optional
+            Flag indicating how to compute the derivative.  A value of False
+            (default) compares nearest values while a value of True compares
+            next-nearest (i.e., central difference).
+        
+        Returns
+        -------
+        newx : numpy.array
+            The x positions corresponding to the dislocation density values.
+        rho : numpy.array
+            The computed dislocation density.
+        """
+        # Default values are class properties
+        if x is None:
+            x = self.x
+        if disregistry is None:
+            disregistry = self.disregistry
+        
+        # Extract values
+        δ = disregistry
+        
+        if cdiff is False:
+            # ρ[i] = (δ[i] - δ[i-1]) / (x[i] - x[i-1])
+            ρ = ((δ[1:] - δ[:-1]).T / (x[1:] - x[:-1])).T
+            
+            # newx is all x except the first
+            newx = x[1:]
+        
+        elif cdiff is True:
+            # ρ[i] = (δ[i+1] - δ[i-1]) / (x[i+1] - x[i-1])
+            ρ = ((δ[2:] - δ[:-2]).T / (x[2:] - x[:-2])).T
+            
+            # newx is all x except the first and last
+            newx = x[1:-1]
+        else:
+            raise TypeError('cdiff must be bool')
+            
+        return (newx, ρ)
+    
+    def misfit_energy(self,
+                      x: Optional[npt.ArrayLike] = None,
+                      disregistry: Optional[npt.ArrayLike] = None) -> float:
+        """
+        Computes the misfit energy for the disregistry using the stored gamma
+        surface
+        
+            E_misfit = Σ γ(δ)Δx
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+            
+        Returns
+        -------
+        float
+            The misfit energy for the dislocation.
+        """
+        # Default values are class properties
+        if x is None:
+            x = self.x
+        if disregistry is None:
+            disregistry = self.disregistry
+        
+        # Extract values
+        δ = disregistry
+        Δx = x[1] - x[0]
+        transform = self.transform
+        gamma = self.gamma
+        
+        # Strip out y-component of disregistry and transform for gamma
+        disreg = np.vstack([δ[:,0], np.zeros(len(δ)), δ[:,2]]).T
+        pos = np.inner(disreg, transform.T)
+        
+        # Σ γ(δ)Δx
+        return Δx * gamma.E_gsf(pos=pos).sum()
+    
+    def elastic_energy(self,
+                       x: Optional[npt.ArrayLike] = None,
+                       disregistry: Optional[npt.ArrayLike] = None) -> float:
+        r"""
+        Computes the short-range configuration-dependent elastic energy term
+        for the dislocation based on the dislocation density and K_tensor.
+        
+            E_elastic = 1/(4π) Σ_i Σ_j χ(i,j,Δx) K_lm ρ_l[i] ρ_m[j]
+            
+            χ(i,j,Δx) = (3/2) Δx² + ψ(i-1,j-1,Δx) + ψ(i,j,Δx) - ψ(i,j-1,Δx) - ψ(j,i-1,Δx)
+            
+            ψ(i,j,Δx) = (1/2) (i-j)² Δx² ln(\|i-j\|Δx)
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        
+        Returns
+        -------
+        float
+            The elastic energy for the dislocation.
+        """
+        # Define subfunctions
+        def χ(i, j, Δx):
+            """
+            Computes the chi subfunction:
+                χ(i,j,Δx) = (3/2) Δx² + ψ(i-1,j-1,Δx) + ψ(i,j,Δx)
+                                      - ψ(i,j-1,Δx) - ψ(j,i-1,Δx)
+            """
+            return 3./2. * Δx**2 + (ψ(i-1, j-1, Δx) + ψ(i, j, Δx)
+                                    - ψ(i, j-1, Δx) - ψ(j, i-1, Δx))
+
+        def ψ(i, j, Δx):
+            """
+            Computes the psi subfunction:
+                ψ(i,j,Δx) = (1/2) (i-j)² Δx² ln(|i-j|Δx)
+            """
+            # Suppress NaN runtime warnings
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", category=RuntimeWarning)
+                
+                # ψ(i,j,Δx) = (1/2) (i-j)² Δx² ln(|i-j|Δx)
+                p = 0.5 * (i - j)**2 * Δx**2 * np.log(np.abs(i - j) * Δx)
+            
+            # Replace NaN values with 0.0
+            p[np.isnan(p)] = 0.0
+            
+            return p
+        
+        # Default values are class properties
+        if x is None:
+            x = self.x
+        if disregistry is None:
+            disregistry = self.disregistry
+        
+        # Extract values
+        δ = disregistry
+        Δx = x[1] - x[0]
+        cdiff = self.cdiffelastic
+        Kij = self.K_tensor
+        
+        ρ = self.disldensity(x=x, disregistry=δ, cdiff=cdiff)[1]
+        j = np.arange(len(ρ), dtype=int)
+        
+        energy = 0.0
+        
+        # Compute elastic energy (looping over i, vectorization over j)
+        # 1/(4π) Σ_i Σ_j χ(i,j,Δx) K_lm ρ_l[i] ρ_m[j]
+        for i in j:
+            energy += np.sum( χ(i, j, Δx) * np.inner(ρ[i].dot(Kij), ρ) ) / (4 * np.pi)
+        
+        return energy
+    
+    def longrange_energy(self) -> float:
+        """
+        Computes the long-range elastic energy term for the dislocation using
+        the K_tensor, Burgers vector and long-range cutoff.  This term is
+        configuration-independent and thus the method takes no parameters.
+        
+            E_longrange = 1/(2π) K_lm b_l b_m ln(L)
+        
+        Returns
+        -------
+        float
+            The long-range energy for the dislocation.
+        """
+        # Extract values
+        Kij = self.K_tensor
+        b = self.burgers
+        L = self.cutofflongrange
+        
+        # Compute long-range energy
+        # 1/(2π) K_lm b_l b_m ln(L)
+        return np.inner(b.dot(Kij), b) * np.log(L) / (2 * np.pi)
+    
+    def stress_energy(self, 
+                      x: Optional[npt.ArrayLike] = None,
+                      disregistry: Optional[npt.ArrayLike] = None) -> float:
+        """
+        Computes the stress energy due to the applied stress, tau.
+        If fullstress is True, the original stress expression by
+        Bulatov and Kaxiras will be used:
+        
+            E_stress = -1/2 Σ_i (x[i]² - x[i-1]²) ρ_l τ_2l
+        
+        If fullstress is False, the alternate stress expression by
+        Shen and Cheng 10.1016/j.scriptamat.2009.04.047 will be used:
+        
+            E_stress = -1/2 Σ_i τ_2l (δ_l[i] + δ_l[i+1]) Δx
+        
+        Note that the Shen and Cheng expression will have a constant
+        error associated with it giving an incorrect overall energy, but
+        should apply a similar force on the dislocation.
+
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        
+        Returns
+        -------
+        float
+            The stress energy for the dislocation.
+        """
+        # Default values are class properties
+        if x is None:
+            x = self.x
+        if disregistry is None:
+            disregistry = self.disregistry
+        
+        # Extract values
+        δ = disregistry
+        Δx = x[1] - x[0]
+        τ = self.tau
+        full = self.fullstress
+        cdiff = self.cdiffstress
+        
+        if full is True:
+            ρ = self.disldensity(x=x, disregistry=δ, cdiff=cdiff)[1]
+            # -1/2 Σ_i (x[i]² - x[i-1]²) ρ_l τ_2l
+            return -0.5 * np.sum((x[1:]**2 - x[:-1]**2) * np.inner(ρ, τ[1,:]))
+            
+        else:
+            # Flip sign on tau so energies match full=True
+            τ = -τ
+            
+            # -1/2 Σ_i τ_2l (δ_l[i] + δ_l[i+1]) Δx
+            return -0.5 * np.sum(np.inner(τ[1,:], (δ[:-1] + δ[1:]) * Δx))
+    
+    def surface_energy(self, 
+                       x: Optional[npt.ArrayLike] = None,
+                       disregistry: Optional[npt.ArrayLike] = None) -> float:
+        """
+        Computes the gradient surface energy correction using beta
+        coefficients.
+        
+            E_surface = Σ_j β_lj / 4 Σ_i ρ_l[i]² Δx
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        
+        Returns
+        -------
+        float
+            The surface energy for the dislocation.
+        """
+        # Default values are class properties
+        if x is None:
+            x = self.x
+        if disregistry is None:
+            disregistry = self.disregistry
+            
+        # Extract values
+        δ = disregistry
+        Δx = x[1] - x[0]
+        β = self.beta
+        cdiff = self.cdiffsurface
+        
+        ρ = self.disldensity(x=x, disregistry=δ, cdiff=cdiff)[1]
+        
+        # Σ_j β_lj / 4 Σ_i ρ_l[i]² Δx
+        return np.sum( np.inner(ρ**2 * Δx, β) ) / 4
+    
+    def nonlocal_energy(self, 
+                        x: Optional[npt.ArrayLike] = None,
+                        disregistry: Optional[npt.ArrayLike] = None) -> float:
+        """
+        Computes the nonlocal energy correction using alpha coefficient(s).
+        
+            E_nonlocal = Σ_m α_m Σ_i δ[i] (δ[i] - (δ[i+m] + δ[i-m]) / 2) Δx
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        
+        Returns
+        -------
+        float
+            The nonlocal energy for the dislocation.
+        """
+        # Default values are class properties
+        if x is None:
+            x = self.x
+        if disregistry is None:
+            disregistry = self.disregistry
+            
+        # Extract values
+        δ = disregistry
+        Δx = x[1] - x[0]
+        αs = self.alpha
+        
+        energy = 0.0
+        
+        # Σ_m α_m Σ_i δ[i] (δ[i] - (δ[i+m] + δ[i-m]) / 2) Δx
+        for num, α in enumerate(αs):
+            m = num + 1
+            dd = δ[m:-m] - 0.5 * (δ[2*m:] + δ[:-2*m])
+            energy += α * np.sum(δ[m:-m] * dd * Δx)
+            
+        return energy
+    
+    def total_energy(self, 
+                     x: Optional[npt.ArrayLike] = None,
+                     disregistry: Optional[npt.ArrayLike] = None) -> float:
+        """
+        Computes the total energy for the dislocation.
+        
+            E_total = E_elastic + E_misfit + E_stress + E_surface + E_nonlocal
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        
+        Returns
+        -------
+        float
+            The total energy for the dislocation.
+        """
+        # Default values are class properties
+        if x is None:
+            x = self.x
+        if disregistry is None:
+            disregistry = self.disregistry
+            
+        return (self.misfit_energy(x, disregistry)
+                + self.elastic_energy(x, disregistry)
+                + self.longrange_energy()
+                + self.stress_energy(x, disregistry)
+                + self.nonlocal_energy(x, disregistry)
+                + self.surface_energy(x, disregistry))
+    
+    def check_energies(self,
+                       x: Optional[npt.ArrayLike] = None,
+                       disregistry: Optional[npt.ArrayLike] = None,
+                       energyperlength_unit: str = 'eV/Å'):
+        """
+        Prints a summary string of all computed energy components.
+
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        energyperlength_unit : str, optional
+            The units of energy per length to report the dislocation line
+            energies in.  Default value is 'eV/Å'.
+        """
+        hasvals = True
+        # Default values are class properties
+        if x is None:
+            try:
+                x = self.x
+            except:
+                hasvals = False
+        if disregistry is None:
+            try:
+                disregistry = self.disregistry
+            except:
+                hasvals = False
+
+        if hasvals:
+            print(f'Dislocation energy terms in {energyperlength_unit}:')
+            print('Misfit energy =    ', uc.get_in_units(self.misfit_energy(x, disregistry), energyperlength_unit))
+            print('Elastic energy =   ', uc.get_in_units(self.elastic_energy(x, disregistry), energyperlength_unit))
+            print('Long-range energy =', uc.get_in_units(self.longrange_energy(), energyperlength_unit))
+            print('Stress energy =    ', uc.get_in_units(self.stress_energy(x, disregistry), energyperlength_unit))
+            print('Surface energy =   ', uc.get_in_units(self.surface_energy(x, disregistry), energyperlength_unit))
+            print('Nonlocal energy =  ', uc.get_in_units(self.nonlocal_energy(x, disregistry), energyperlength_unit))
+            print('Total energy =     ', uc.get_in_units(self.total_energy(x, disregistry), energyperlength_unit))
+        else:
+            print('x and disregistry must be set/given to check energies')
+    
+    def disregistry_plot(self, 
+                         x: Optional[npt.ArrayLike] = None,
+                         disregistry: Optional[npt.ArrayLike] = None,
+                         figsize: Optional[tuple] = None,
+                         length_unit: str = 'Å') -> plt.figure:
+        """
+        Creates a simple matplotlib figure showing the disregistry profiles.
+
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.
+        figsize : tuple, optional
+            matplotlib figure figsize parameter.  Default value is (10, 6).
+        length_unit : str, optional
+            The unit of length to display positions and disregistry values in.
+            Default value is 'Å'.
+            
+        Returns
+        -------
+        matplotlib.pyplot.figure
+            The generated figure allowing users to perform additional
+            modifications.
+        """
+        hasvals = True
+        # Default values are class properties
+        if x is None:
+            try:
+                x = self.x
+            except:
+                hasvals = False
+        if disregistry is None:
+            try:
+                disregistry = self.disregistry
+            except:
+                hasvals = False
+        if hasvals:
+
+            if figsize is None:
+                figsize = (10, 6)
+
+            fig = plt.figure(figsize=figsize)
+            
+            x = uc.get_in_units(x, length_unit)
+            disregistry = uc.get_in_units(disregistry, length_unit)
+            plt.plot(x, disregistry[:, 0], label='edge disregistry')
+            plt.plot(x, disregistry[:, 1], label='normal disregistry')
+            plt.plot(x, disregistry[:, 2], label='screw disregistry')
+            plt.legend(fontsize='xx-large')
+            plt.xlabel(f'x (${length_unit}$)', size='xx-large')
+            plt.ylabel(f'disregistry (${length_unit}$', size='xx-large')
+            return fig
+
+        else:
+            print('x and disregistry must be set/given to plot')
+
+    def E_gsf_surface_plot(self, 
+                           x: Optional[npt.ArrayLike] = None,
+                           disregistry: Optional[npt.ArrayLike] = None,
+                           fmt: str = 'ro-',
+                           normalize: Optional[bool] = False,
+                           smooth: bool = True, 
+                           a1vect: Optional[npt.ArrayLike] = None,
+                           a2vect: Optional[npt.ArrayLike] = None,
+                           xvect: Optional[npt.ArrayLike] = None,
+                           length_unit: str = 'Å',
+                           energyperarea_unit: str = 'eV/Å^2',
+                           numx: int = 100,
+                           numy: int = 100,
+                           figsize: Optional[tuple] = None,
+                           **kwargs) -> plt.figure:
+        """
+        Extends the GammaSurface.E_gsf_surface_plot() method to plot the
+        disregistry path on top of it.
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates. If x
+            or disregistry are not set/given, then the disregistry path will
+            not be added.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.  If x
+            or disregistry are not set/given, then the disregistry path will
+            not be added.
+        fmt : str, optional
+            The matplotlib.pyplot.plot fmt parameter for the disregistry path
+            line, i.e. color, marker and line style options.  Default value is
+            'ro-': red with circle markers and solid line.
+        normalize : bool, optional
+            Flag indicating if axes are Cartesian (False, default) or
+            normalized by a1, a2 vectors (True).
+        smooth : bool, optional
+            If True (default), then plot shows smooth interpolated values.
+            If False, plot shows nearest raw data values.
+        a1vect : array-like object, optional
+            Crystal vector for the a1 vector to use for plotting.  Default
+            value of None uses the saved a1vect.
+        a2vect : array-like object, optional
+            Crystal vector for the a2 vector to use for plotting.  Default
+            value of None uses the saved a2vect.
+        xvect : array-like object, optional
+            Crystal vector to align with the plotting x-axis for 
+            non-normalized plots.  If not given, this is taken as the Cartesian
+            of a1vect.
+        length_unit : str, optional
+            The unit of length to display non-normalized axes values in.
+            Default value is 'Å'.
+        energyperarea_unit : str, optional
+            The unit of energy per area to display the stacking fault energies
+            in. Default value is 'eV/Å^2'.
+        numx : int, optional
+            The number of plotting points to use along the x-axis.  Default
+            value is 100.
+        numy : int, optional
+            The number of plotting points to use along the y-axis.  Default
+            value is 100.       
+        figsize : tuple or None, optional
+            The figure's x,y dimensions.  If None (default), the values are
+            scaled such that the x,y spacings are approximately equal, and the
+            larger of the two values is set to 10.
+        **kwargs : dict, optional
+            Additional keywords are passed into the underlying 
+            matplotlib.pyplot.pcolormesh(). This allows control of such things
+            like the colormap (cmap).
+            
+        Returns
+        -------
+        matplotlib.pyplot.figure
+            The generated figure allowing users to perform additional
+            modifications.
+        """
+
+        # Generate the surface plot
+        fig = self.gamma.E_gsf_surface_plot(normalize=normalize, smooth=smooth, 
+                                            a1vect=a1vect, a2vect=a2vect, xvect=xvect,
+                                            length_unit=length_unit, energyperarea_unit=energyperarea_unit,
+                                            numx=numx, numy=numy, figsize=figsize, **kwargs)
+        
+        hasvals = True
+        # Default values are class properties
+        if x is None:
+            try:
+                x = self.x
+            except:
+                hasvals = False
+        if disregistry is None:
+            try:
+                disregistry = self.disregistry
+            except:
+                hasvals = False
+        if hasvals:
+
+            # Get xvect direction
+            if xvect is None:
+                if a1vect is None:
+                    a1vect = self.gamma.a1vect
+                xvect = np.dot(a1vect, self.gamma.box.vects)
+
+            # Transform disregistry to gamma surface pos
+            pos = disregistry.dot(self.transform)
+            
+            # Transform to x, y plotting coordinates and plot
+            x, y = self.gamma.pos_to_xy(pos, xvect=xvect)
+            x = uc.get_in_units(x, length_unit)
+            y = uc.get_in_units(y, length_unit)
+            plt.plot(x, y, fmt)
+
+        return fig
+
+    def E_gsf_vs_x_plot(self, 
+                        x: Optional[npt.ArrayLike] = None,
+                        disregistry: Optional[npt.ArrayLike] = None,
+                        figsize: Optional[tuple] = None, 
+                        length_unit: str = 'Å',
+                        energyperarea_unit: str = 'eV/Å^2') -> plt.figure:
+        """
+        Generates a plot of the stacking fault energy, i.e. misfit energy,
+        associated with the disregistry values for each x coordinate.
+        
+        Parameters
+        ----------
+        x : array-like object, optional
+            x-coordinates.  Default value is the stored x-coordinates. If x
+            or disregistry are not set/given, then the disregistry path will
+            not be added.
+        disregistry : array-like object, optional
+            (N, 3) shaped array of disregistry vectors at each x-coordinate.
+            Default value is the stored disregistry values.  If x
+            or disregistry are not set/given, then the disregistry path will
+            not be added.
+        figsize : tuple or None, optional
+            The figure's x,y dimensions.  If None (default), then a figure
+            size of (10, 6) will be generated.
+        length_unit : str, optional
+            The unit of length to display x coordinates in.  Default value is
+            'Å'.
+        energyperarea_unit : str, optional
+            The unit of energy per area to display the stacking fault energies
+            in. Default value is 'eV/Å^2'.
+            
+        Returns
+        -------
+        matplotlib.pyplot.figure
+            The generated figure allowing users to perform additional
+            modifications.
+        """
+        hasvals = True
+        # Default values are class properties
+        if x is None:
+            try:
+                x = self.x
+            except:
+                hasvals = False
+        if disregistry is None:
+            try:
+                disregistry = self.disregistry
+            except:
+                hasvals = False
+        if hasvals:
+
+            if figsize is None:
+                figsize=(10,6)
+
+            gsf = self.gamma.E_gsf(pos=disregistry.dot(self.transform))
+            
+            fig = plt.figure(figsize=figsize)
+            plt.plot(uc.get_in_units(x, length_unit),
+                     uc.get_in_units(gsf, energyperarea_unit))
+            plt.xlabel(f'x-coordinate (${length_unit}$)', size='xx-large')
+            plt.ylabel(f'Stacking fault energy (${energyperarea_unit}$)', size='xx-large')
+            return fig
+        
+        else:
+            print('x and disregistry must be set/given to check stacking fault energies')
+
+
+    def load(self, 
+             model: Union[str, io.IOBase, DM],
+             gamma: Optional[GammaSurface] = None):
+        """
+        Load solution from a data model.
+        
+        Parameters
+        ----------
+        model : str, file-like object or DataModelDict
+            The semi-discrete-Peierls-Nabarro data model to load.
+        gamma : atomman.defect.GammaSurface, optional
+            The gamma surface to use.  If not given, will check to see if the
+            content is inside model.
+        
+        Raises
+        ------
+        ValueError
+            If the gamma surface information is not given and it is not found
+            in model.
+        """
+        
+        # Identify model element
+        try:
+            sdpn = DM(model).find('semidiscrete-variational-Peierls-Nabarro')
+        except:
+            sdpn = DM(model).find('semi-discrete-Peierls-Nabarro')
+        
+        # Load calculation parameters
+        params = sdpn['parameter']
+        try:
+            self.__transform = uc.value_unit(params['transform'])
+        except: 
+            self.__transform = uc.value_unit(params['axes'])
+        self.__K_tensor = uc.value_unit(params['K_tensor'])
+        self.__burgers = uc.value_unit(params['burgers'])
+        self.tau = uc.value_unit(params['tau'])
+        self.alpha = uc.value_unit(params['alpha'])
+        self.beta = uc.value_unit(params['beta'])
+        self.cutofflongrange = uc.value_unit(params['cutofflongrange'])
+        self.fullstress = params['fullstress']
+        self.cdiffelastic = params['cdiffelastic']
+        self.cdiffsurface = params['cdiffsurface']
+        self.cdiffstress = params['cdiffstress']
+        self.min_method = params['min_method']
+        self.min_options = params['min_options']
+        self.min_kwargs = params.get('min_kwargs', None)
+        
+        # Load gamma
+        if gamma is None:
+            try:
+                gamma = GammaSurface(model)
+            except:
+                raise ValueError('No gamma surface in model or given!')
+        elif not isinstance(gamma, GammaSurface):
+            gamma = GammaSurface(gamma)
+        self.__gamma = gamma
+        
+        # Load calculation solution
+        solution = sdpn['solution']
+        self.x = uc.value_unit(solution['x'])
+        self.disregistry = uc.value_unit(solution['disregistry'])
+    
+    def model(self, 
+              length_unit: str = 'Å',
+              energyperarea_unit: str = 'eV/Å^2',
+              pressure_unit: str = 'GPa',
+              include_gamma: bool = False) -> DM:
+        """
+        Generate a data model for the object.
+        
+        Parameters
+        ----------
+        length_unit : str, optional
+            The unit of length to save values as.  Default is 'Å'.
+        energyperarea_unit : str, optional
+            The unit of energy per area to save fault energy values as.  Only
+            used if the gamma surface information is included.  Default value
+            is 'eV/Å^2'.
+        pressure_unit : str, optional
+            The unit of pressure to save values as.  Default is 'GPa'.
+        include_gamma : bool, optional
+            Flag indicating if the gamma surface data is to be included.
+            Default value is False.
+            
+        Returns
+        -------
+        DataModelDict
+            The data model containing all input parameters and the current
+            disregistry vectors.
+        """
+        model = DM()
+        model['semidiscrete-variational-Peierls-Nabarro'] = sdpn = DM()
+        
+        sdpn['parameter'] = params = DM()
+        params['transform'] = uc.model(self.transform, None)
+        params['K_tensor'] = uc.model(self.K_tensor, pressure_unit)
+        params['tau'] = uc.model(self.tau, pressure_unit)
+        params['alpha'] = uc.model(self.alpha, pressure_unit+'/'+length_unit)
+        
+        params['beta'] = uc.model(self.beta, pressure_unit+'*'+length_unit)
+        params['cdiffelastic'] = self.cdiffelastic
+        params['cdiffsurface'] = self.cdiffsurface
+        params['cdiffstress'] = self.cdiffstress
+        params['cutofflongrange'] = uc.model(self.cutofflongrange, length_unit)
+        params['burgers'] = uc.model(self.burgers, length_unit)
+        params['fullstress'] = self.fullstress
+        params['min_method'] = self.min_method
+        params['min_options'] = self.min_options
+        if len(self.min_kwargs) > 0:
+            params['min_kwargs'] = self.min_kwargs
+        
+        if include_gamma is True:
+            sdpn['generalized-stacking-fault'] = self.gamma.model(
+                                                  length_unit=length_unit,
+                                                  energyperarea_unit=energyperarea_unit)
+        
+        sdpn['solution'] = solution = DM()
+        solution['x'] = uc.model(self.x, length_unit)
+        solution['disregistry'] = uc.model(self.disregistry, length_unit)
+        
+        return model

atomman/source/atomman/defect/StackingFault.py

@@ -0,0 +1,667 @@
+# coding: utf-8
+# Standard Python libraries
+import io
+from copy import deepcopy
+from typing import Generator, Optional, Tuple, Union
+
+from DataModelDict import DataModelDict as DM
+
+# http://www.numpy.org/
+import numpy as np
+import numpy.typing as npt
+
+from yabadaba.record import Record
+
+# atomman imports
+from ..tools import miller
+from . import FreeSurface
+from .. import System, load
+from ..library import load_record, Database
+
+class StackingFault(FreeSurface):
+    """
+    Class for generating stacking fault atomic configurations. 
+    """
+    def __init__(self,
+                 hkl: npt.ArrayLike,
+                 ucell: System,
+                 cutboxvector: str = 'c',
+                 maxindex: Optional[int] = None,
+                 a1vect_uvw: Optional[npt.ArrayLike] = None,
+                 a2vect_uvw: Optional[npt.ArrayLike] = None,
+                 conventional_setting: str = 'p',
+                 shift: Optional[npt.ArrayLike] = None,
+                 shiftindex: Optional[int] = None,
+                 shiftscale: bool = False,
+                 tol: float = 1e-8):
+        """
+        Class initializer.  Identifies the proper rotations for the given hkl plane
+        and cutboxvector, and creates the rotated cell.
+        
+        Parameters
+        ----------
+        hkl : array-like object
+            The free surface plane to generate expressed in either 3 indices
+            Miller (hkl) format or 4 indices Miller-Bravais (hkil) format.
+        ucell : atomman.System
+            The unit cell to use in generating the system.
+        cutboxvector : str, optional
+            Specifies which of the three box vectors corresponds to the
+            out-of-plane vector.  Default value is c.
+        maxindex : int, optional
+            Max uvw index value to use in identifying the best uvw set for the
+            out-of-plane vector.  If not given, will use the largest absolute
+            index between the given hkl and the initial in-plane vector guesses.
+        a1vect_uvw : array-like object, optional
+            The crystal vector to use for one of the two shifting vectors.  If
+            not given, will be set to the shortest in-plane lattice vector.
+        a2vect_uvw : array-like object, optional
+            The crystal vector to use for one of the two shifting vectors.  If
+            not given, will be set to the shortest in-plane lattice vector not
+            parallel to a1vect_uvw.
+        conventional_setting : str, optional
+            Allows for rotations of a primitive unit cell to be determined from
+            (hkl) indices specified relative to a conventional unit cell.  Allowed
+            settings: 'p' for primitive (no conversion), 'f' for face-centered,
+            'i' for body-centered, and 'a', 'b', or 'c' for side-centered.  Default
+            behavior is to perform no conversion, i.e. take (hkl) relative to the
+            given ucell.
+        shift : array-like object, optional
+            Applies a shift to all atoms. Different values allow for free surfaces with
+            different termination planes to be selected.  shift is taken as absolute
+            if shiftscale is False, or relative to the rotated cell's box vectors
+            if shiftscale is True.  Cannot be given with shiftindex.  If
+            neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftindex : float, optional
+            The index of the identified shifts based on the rotated
+            cell to use.  Different values allow for the selection of different
+            atomic planes neighboring the slip plane.  Cannot be given with shift.
+            If neither shift nor shiftindex is given then shiftindex = 0 is used.
+        shiftscale : bool, optional
+            If False (default), a given shift value will be taken as absolute
+            Cartesian.  If True, a given shift will be taken relative to the
+            rotated cell's box vectors.
+        tol : float, optional
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        """
+        super().__init__(hkl, ucell, cutboxvector=cutboxvector, maxindex=maxindex,
+                 conventional_setting=conventional_setting, 
+                 shift=shift, shiftindex=shiftindex, shiftscale=shiftscale, tol=tol)
+
+        # Extract a1vect and a2vect values from uvws and rcell.box
+        if a1vect_uvw is None and a2vect_uvw is None:
+
+            # Set a1index and a2index based on cutboxvector
+            if self.cutboxvector == 'a':
+                a1index, a2index = 1, 2
+            elif self.cutboxvector == 'b':
+                a1index, a2index = 2, 0
+            elif self.cutboxvector == 'c':
+                a1index, a2index = 0, 1
+
+            self.a1vect_uvw = self.uvws[a1index]
+            self.a2vect_uvw = self.uvws[a2index]
+
+        # Set given a1vect_uvw and a2vect_uvw values
+        elif a1vect_uvw is not None and a2vect_uvw is not None:
+            self.a1vect_uvw = a1vect_uvw
+            self.a2vect_uvw = a2vect_uvw
+
+        else:
+            raise ValueError('a1vect_uvw and a2vect_uvw either both need to be given or not given')
+
+        # Set empty attributes
+        self.__faultpos_cart = None
+        self.__faultpos_rel = None
+        self.__abovefault = None
+
+    @classmethod
+    def fromrecord(cls,
+                   record: Union[str, io.IOBase, DM, Record],
+                   ucell: Union[System, str, io.IOBase],
+                   maxindex: Optional[int] = None,
+                   tol: float = 1e-7):
+        """
+        Construct a StackingFault object based on parameters in a stacking_fault
+        record and unit cell information.
+
+        Parameters
+        ----------
+        record : atomman.library.record.StackingFault, str, file-like object or DataModelDict
+            A StackingFault record object or the model contents for one.
+        ucell : atomman.System
+            The unit cell to use in generating the system.
+        maxindex : int, optional
+            Max uvw index value to use in identifying the best uvw set for the
+            out-of-plane vector.  If not given, will use the largest absolute
+            index between the given hkl and the initial in-plane vector guesses.
+        tol : float, optional
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        """
+        # Create record object if needed
+        if not isinstance(record, Record):
+            record = load_record('stacking_fault', model=record)
+
+        # Extract parameters in the record
+        hkl = miller.fromstring(record.parameters['hkl'])
+        shiftindex = int(record.parameters.get('shiftindex', 0))
+        cutboxvector = record.parameters['cutboxvector']
+        conventional_setting = record.parameters.get('conventional_setting', 'p')
+        a1vect_uvw = miller.fromstring(record.parameters['a1vect_uvw'])
+        a2vect_uvw = miller.fromstring(record.parameters['a2vect_uvw'])
+
+        return cls(hkl=hkl, ucell=ucell, cutboxvector=cutboxvector,
+                   maxindex=maxindex, shiftindex=shiftindex,
+                   a1vect_uvw=a1vect_uvw, a2vect_uvw=a2vect_uvw,
+                   conventional_setting=conventional_setting, tol=tol)
+
+    @classmethod
+    def fromdatabase(cls,
+                     name: Optional[str] = None,
+                     ucell: Optional[System] = None,
+                     database: Optional[Database] = None,
+                     prompt: bool = True,
+                     maxindex: Optional[int] = None,
+                     tol: float = 1e-7,
+                     **kwargs):
+        """
+        Construct a StackingFault object based on record(s) retrieved from the
+        reference database.
+
+        Parameters
+        ----------
+        name : str or None, optional
+            The name of the stacking_fault record to retrieve from the database.
+            Alternatively, you can use any other query keyword arguments supported
+            by the stacking_fault record style (see **kwargs below for more info).
+        ucell : atomman.System or None, optional
+            The unit cell to use in generating the system.  If None (default), then
+            the crystal_prototype record that matches the defect's family setting
+            will be loaded from the database.  Note that if None then the
+            crystal-specific info (lattice constants and symbols) should be given
+            here as kwargs (see below).
+        database : atomman.library.Database or None, optional
+            A Database object to use to fetch the records.  If None (default), then
+            a new Database instance will be created.
+        prompt : bool
+            If prompt=True (default) then a screen input will ask for a selection
+            if multiple matching stacking_fault (or crystal_prototype) records are
+            found.  If prompt=False, then an error will be thrown if multiple
+            matches are found.
+        maxindex : int, optional
+            Max uvw index value to use in identifying the best uvw set for the
+            out-of-plane vector.  If not given, will use the largest absolute
+            index between the given hkl and the initial in-plane vector guesses.
+        tol : float, optional
+            Tolerance parameter used to round off near-zero values.  Default
+            value is 1e-8.
+        **kwargs : any
+            The recognized kwargs include the query keywords for free_surface
+            records (key, id, family, hkl, shiftindex, cutboxvector), and the
+            crystal-specific parameters recognized by the prototype load style
+            (a, b, c, alpha, beta, gamma, symbols).  The non-trivial
+            crystal-specific parameters should be for the crystal if ucell is
+            not given above as the crystal prototype lacks this information.
+        """
+        # Initialize a database if needed
+        if database is None:
+            database = Database()
+
+        # Extract ucell parameters from kwargs
+        prototype_kwargs = {}
+        prototype_kwargs_names = ['a', 'b', 'c', 'alpha', 'beta', 'gamma', 'symbols']
+        for prototype_kwargs_name in prototype_kwargs_names:
+            if prototype_kwargs_name in kwargs:
+                prototype_kwargs[prototype_kwargs_name] = kwargs.pop(prototype_kwargs_name)
+
+        # Fetch matching defect record
+        record = database.get_record('stacking_fault', name=name, prompt=prompt, **kwargs)
+
+        # Fetch crystal prototype unit cell if needed
+        if ucell is None:
+            ucell = load('prototype', name=record.family, **prototype_kwargs)
+        else:
+            if len(prototype_kwargs) > 0:
+                raise ValueError('crystal-specific kwargs cannot be given with ucell')
+
+        return cls.fromrecord(record=record, ucell=ucell, maxindex=maxindex, tol=tol)
+
+    @property
+    def a1vect_uvw(self) -> np.ndarray:
+        """
+        numpy.ndarray : One of the two conventional lattice shift vectors in Miller
+        or Miller-Bravais indices.
+        """
+        return self.__a1vect_uvw
+
+    @property
+    def a2vect_uvw(self) -> np.ndarray:
+        """
+        numpy.ndarray : One of the two conventional lattice shift vectors in Miller
+        or Miller-Bravais indices.
+        """
+        return self.__a2vect_uvw
+
+    @a1vect_uvw.setter
+    def a1vect_uvw(self, value: npt.ArrayLike):
+
+        value = np.asarray(value)
+
+        # Check shape and convert [uvtw] to [uvw] if needed
+        if value.shape == (4,):
+            uvw = miller.vector4to3(value)
+        elif value.shape == (3,):
+            uvw = value
+            if self.hkl.shape == (4,):
+                value = miller.vector3to4(value)
+        else:
+            raise ValueError('Invalid uvw shape: must have 3 or 4 values.')
+
+        # Convert to primitive cell
+        uvw = miller.vector_conventional_to_primitive(uvw, self.conventional_setting)
+
+        # Convert to Cartesian wrt rotated system
+        cart = self.transform.dot(miller.vector_crystal_to_cartesian(uvw, self.ucell.box))
+
+        # Check that Cartesian vector is in slip plane
+        if not np.isclose(cart[self.cutindex], 0.0):
+            raise ValueError(f'shift vector {value} not in fault plane {self.hkl}')
+
+        # Save uvw and cart
+        self.__a1vect_uvw = value
+        self.__a1vect_cart = cart
+
+    @a2vect_uvw.setter
+    def a2vect_uvw(self, value: npt.ArrayLike):
+
+        value = np.asarray(value)
+
+        # Check shape and convert [uvtw] to [uvw] if needed
+        if value.shape == (4,):
+            uvw = miller.vector4to3(value)
+        elif value.shape == (3,):
+            uvw = value
+            if self.hkl.shape == (4,):
+                value = miller.vector3to4(value)
+        else:
+            raise ValueError('Invalid uvw shape: must have 3 or 4 values.')
+
+        # Convert to primitive cell
+        uvw = miller.vector_conventional_to_primitive(uvw, self.conventional_setting)
+
+        # Convert to Cartesian wrt rotated system
+        cart = self.transform.dot(miller.vector_crystal_to_cartesian(uvw, self.ucell.box))
+
+        # Check that Cartesian vector is in slip plane
+        if not np.isclose(cart[self.cutindex], 0.0):
+            raise ValueError(f'shift vector {value} not in fault plane {self.hkl}')
+
+        # Save uvw and cart
+        self.__a2vect_uvw = value
+        self.__a2vect_cart = cart
+
+    @property
+    def a1vect_cart(self) -> np.ndarray:
+        """numpy.ndarray : One of the two shift vectors in Cartesian relative to system."""
+        return self.__a1vect_cart
+
+    @property
+    def a2vect_cart(self) -> np.ndarray:
+        """numpy.ndarray : One of the two shift vectors in Cartesian relative to system."""
+        return self.__a2vect_cart
+
+    @property
+    def faultpos_cart(self) -> float:
+        """float : The Cartesian position of the slip plane."""
+        if self.__faultpos_cart is not None:
+            return self.__faultpos_cart
+        else:
+            raise AttributeError('system not yet built. Use build_system() or surface().')
+
+    @property
+    def faultpos_rel(self) -> float:
+        """float : The fractional position of the slip plane."""
+        if self.__faultpos_rel is not None:
+            return self.__faultpos_rel
+        else:
+            raise AttributeError('system not yet built. Use build_system() or surface().')
+
+    @property
+    def abovefault(self) -> list:
+        """list : Indices of all atoms in system above the slip plane."""
+        if self.__abovefault is not None:
+            return self.__abovefault
+        else:
+            raise AttributeError('system not yet built. Use build_system() or surface().')
+
+    @faultpos_cart.setter
+    def faultpos_cart(self, value: float):
+
+        # faultpos_rel = (faultpos_cart - origin) / width (for origin, width || cutindex)
+        faultpos_rel = ((value - self.system.box.origin[self.cutindex])
+                       / self.system.box.vects[self.cutindex, self.cutindex])
+        if faultpos_rel < 0.0 or faultpos_rel > 1.0:
+            raise ValueError('faultpos is outside system')
+
+        self.__faultpos_rel = faultpos_rel
+        self.__faultpos_cart = value
+
+        # Identify atoms above fault plane position
+        self.__abovefault = self.system.atoms.pos[:, self.cutindex] > (self.faultpos_cart)
+
+    @faultpos_rel.setter
+    def faultpos_rel(self, value: float):
+
+        if value < 0.0 or value > 1.0:
+            raise ValueError('faultpos is outside system')
+
+        self.__faultpos_rel = value
+
+        # faultpos_cart = origin + faultpos_rel * width (for origin, width || cutindex) 
+        self.__faultpos_cart = (self.system.box.origin[self.cutindex] 
+                              + self.faultpos_rel 
+                              * self.system.box.vects[self.cutindex, self.cutindex])
+
+        # Identify atoms above fault plane position
+        self.__abovefault = self.system.atoms.pos[:, self.cutindex] > (self.faultpos_cart)
+
+    def surface(self,
+                shift: Optional[npt.ArrayLike] = None,
+                shiftindex: Optional[int] = None,
+                shiftscale: bool = None,
+                vacuumwidth: Optional[float] = None,
+                minwidth: Optional[float] = None,
+                sizemults: Optional[list] = None,
+                even: bool = False,
+                faultpos_rel: Optional[float] = None,
+                faultpos_cart: Optional[float] = None) -> System:
+        """
+        Generates the free surface atomic system, which is used as the basis for generating
+        the stacking fault configuration(s).
+        
+        Parameters
+        ----------
+        shift : array-like object, optional
+            Applies a shift to all atoms. Different values allow for free surfaces with
+            different termination planes to be selected.  shift is taken as absolute
+            if shiftscale is False, or relative to the rotated cell's box vectors
+            if shiftscale is True.  Cannot be given with shiftindex.  If
+            neither shift nor shiftindex is given then the current value set to the
+            shift attribute will be used.
+        shiftindex : float, optional
+            The index of the identified shifts based on the rotated
+            cell to use.  Different values allow for the selection of different
+            atomic planes neighboring the slip plane.  Cannot be given with shift.
+            If neither shift nor shiftindex is given then the current value set to
+            the shift attribute will be used.
+        shiftscale : bool, optional
+            If False (default), a given shift value will be taken as absolute
+            Cartesian.  If True, a given shift will be taken relative to the
+            rotated cell's box vectors.
+        vacuumwidth : float, optional
+            If given, the free surface is created by modifying the system's box to insert
+            a region of vacuum with this width. This is typically used for DFT calculations
+            where it is computationally preferable to insert a vacuum region and keep all
+            dimensions periodic.
+        sizemults : list or tuple, optional
+            The three System.supersize multipliers [a_mult, b_mult, c_mult] to use on the
+            rotated cell to build the final system. Note that the cutboxvector sizemult
+            must be an integer and not a tuple.  Default value is [1, 1, 1].
+        minwidth : float, optional
+            If given, the sizemult along the cutboxvector will be selected such that the
+            width of the resulting final system in that direction will be at least this
+            value. If both sizemults and minwidth are given, then the larger of the two
+            in the cutboxvector direction will be used. 
+        even : bool, optional
+            A True value means that the sizemult for cutboxvector will be made an even
+            number by adding 1 if it is odd.  Default value is False.
+        faultpos_rel : float, optional
+            The position to place the slip plane within the system given as a
+            relative coordinate along the out-of-plane direction.  faultpos_rel
+            and faultpos_cart cannot both be given.  Default value is 0.5 if 
+            faultpos_cart is also not given.
+        faultpos_cart : float, optional
+            The position to place the slip plane within the system given as a
+            Cartesian coordinate along the out-of-plane direction.  faultpos_rel
+            and faultpos_cart cannot both be given.
+        
+        Returns
+        -------
+        atomman.System
+            The free surface atomic system.
+        """
+        super().surface(shift=shift, shiftindex=shiftindex, shiftscale=shiftscale,
+                        vacuumwidth=vacuumwidth, minwidth=minwidth,
+                        sizemults=sizemults, even=even)
+
+        # Set Cartesian fault position
+        if faultpos_cart is not None:
+            if faultpos_rel is not None:
+                raise ValueError('faultpos_rel and faultpos_cart cannot both be given')
+            self.faultpos_cart = faultpos_cart
+
+        # Set relative fault position
+        elif faultpos_rel is not None:
+            self.faultpos_rel = faultpos_rel
+
+        # Set default fault position
+        else:
+            self.faultpos_rel = 0.5
+
+        return self.system
+
+    def fault(self,
+              a1: Optional[float] = None,
+              a2: Optional[float] = None,
+              outofplane: Optional[float] = None,
+              faultshift: Optional[npt.ArrayLike] = None,
+              minimum_r: Optional[float] = None,
+              a1vect_uvw: Optional[npt.ArrayLike] = None,
+              a2vect_uvw: Optional[npt.ArrayLike] = None,
+              faultpos_cart: Optional[float] = None,
+              faultpos_rel: Optional[float] = None) -> System:
+        """
+        Generates a fault configuration by displacing all atoms above the slip
+        plane.
+
+        Parameters
+        ----------
+        a1 : float, optional
+            The fractional coordinate of a1vect to shift by. 
+            Default value is 0.0.
+        a2 : float, optional
+            The fractional coordinate of a2vect to shift by. 
+            Default value is 0.0. 
+        outofplane : float, optional
+            An out-of-plane shift, given in absolute units.
+            Default value is 0.0.
+        faultshift : array-like object, optional
+            The full shifting vector to displace the atoms above the slip
+            plane by.  Cannot be given with a1, a2, or outofplane.
+        minimum_r : float, optional
+            Specifies the minimum allowed interatomic spacing across the slip
+            plane.  If any sets of atoms are closer than this value then the
+            outofplane shift is increased.  Default value is None, which
+            performs no adjustment.
+        a1vect_uvw : array-like object, optional
+            The crystal vector to use for one of the two shifting vectors.
+            Included here for those wishing to override the values set during
+            class initialization.
+        a2vect_uvw : array-like object, optional
+            The crystal vector to use for one of the two shifting vectors.
+            Included here for those wishing to override the values set during
+            class initialization.
+        faultpos_rel : float, optional
+            The position to place the slip plane within the system given as a
+            relative coordinate along the out-of-plane direction.  Included
+            here for those wishing to override the value set when surface()
+            was called.  faultpos_rel and faultpos_cart cannot both be given.
+        faultpos_cart : float, optional
+            The position to place the slip plane within the system given as a
+            Cartesian coordinate along the out-of-plane direction.  Included
+            here for those wishing to override the value set when surface()
+            was called.  faultpos_rel and faultpos_cart cannot both be given.
+
+        Returns
+        -------
+        atomman.System
+            The atomic configuration with stacking fault shift
+        """
+        # Update uvws and faultpos if given
+        if a1vect_uvw is not None:
+            self.a1vect_uvw = a1vect_uvw
+        if a2vect_uvw is not None:
+            self.a2vect_uvw = a2vect_uvw
+        if faultpos_cart is not None:
+            if faultpos_rel is not None:
+                raise ValueError('faultpos_rel and faultpos_cart cannot both be given')
+            self.faultpos_cart = faultpos_cart
+        elif faultpos_rel is not None:
+            self.faultpos_rel = faultpos_rel
+
+        # Define out of plane unit vector
+        ovect = np.zeros(3)
+        ovect[self.cutindex] = 1.0
+
+        # Identify the two non-cut indices
+        inindex = []
+        for i in range(3):
+            if i != self.cutindex:
+                inindex.append(i)
+
+        # Calculate faultshift
+        if a1 is not None or a2 is not None or outofplane is not None:
+            if faultshift is not None:
+                raise ValueError('a1, a2, outofplane cannot be given with faultshift')
+            if a1 is None:
+                a1 = 0.0
+            if a2 is None:
+                a2 = 0.0
+            if outofplane is None:
+                outofplane = 0.0
+            faultshift = a1 * self.a1vect_cart + a2 * self.a2vect_cart + outofplane * ovect
+
+        # Set default faultshift
+        elif faultshift is None:
+            faultshift = np.array([0.0, 0.0, 0.0])
+
+        # Shift atoms above the fault by faultshift
+        sfsystem = deepcopy(self.system)
+        sfsystem.atoms.pos[self.abovefault] += faultshift
+        sfsystem.wrap()
+
+        # Add additional outofplane shift if necessary
+        if minimum_r is not None:
+            # Get all atoms within minimum_r of fault position
+            top_pos = sfsystem.atoms.pos[self.abovefault]
+            top_pos = top_pos[top_pos[:, self.cutindex] <= self.faultpos_cart + minimum_r] 
+            bot_pos = sfsystem.atoms.pos[~self.abovefault] # 
+            bot_pos = bot_pos[bot_pos[:, self.cutindex] >= self.faultpos_cart - minimum_r]
+            if top_pos.shape[0] > 0 and bot_pos.shape[0] > 0:
+                dmag_min = minimum_r
+                dvect_min = None
+
+                for i in range(top_pos.shape[0]):
+                    dvect = sfsystem.dvect(bot_pos, top_pos[i])
+                    if dvect.shape == (3,):
+                        dvect = dvect.reshape(1,3)
+                    dmag = np.linalg.norm(dvect, axis=1)
+                    i = np.argmin(dmag)
+                    if dmag[i] < dmag_min:
+                        dmag_min = dmag[i]
+                        dvect_min = dvect[i]
+
+                if dvect_min is not None:
+
+                    new = (minimum_r**2 - dvect_min[inindex[0]]**2 - dvect_min[inindex[1]]**2)**0.5
+                    outofplane = new - dvect_min[self.cutindex]
+                    faultshift = outofplane * ovect
+                    sfsystem.atoms.pos[self.abovefault] += faultshift
+                    sfsystem.wrap()
+
+        return sfsystem
+
+    def iterfaultmap(self,
+                     num_a1: Optional[int] = None,
+                     num_a2: Optional[int] = None,
+                     outofplane: Optional[float] = None,
+                     minimum_r: Optional[float] = None,
+                     a1vect_uvw: Optional[npt.ArrayLike] = None,
+                     a2vect_uvw: Optional[npt.ArrayLike] = None,
+                     faultpos_cart: Optional[float] = None,
+                     faultpos_rel: Optional[float] = None
+                     ) -> Generator[Tuple[float, float, System], None, None]:
+        """
+        Iterates over generalized stacking fault configurations associated
+        with a 2D map of equally spaced a1, a2 coordinates.
+
+        Parameters
+        ----------
+        num_a1 : int
+            The number of a1 values to generate systems for.  
+            Default value is 1 (only generate for a1=0.0).
+        num_a2 : int
+            The number of a2 values to generate systems for.  
+            Default value is 1 (only generate for a2=0.0).
+        outofplane : float, optional
+            An out-of-plane shift, given in absolute units.
+            Default value is 0.0.
+        minimum_r : float, optional
+            Specifies the minimum allowed interatomic spacing across the slip
+            plane.  If any sets of atoms are closer than this value then the
+            outofplane shift is increased.  Default value is None, which
+            performs no adjustment.
+        a1vect_uvw : array-like object, optional
+            The crystal vector to use for one of the two shifting vectors.
+            Included here for those wishing to override the values set during
+            class initialization.
+        a2vect_uvw : array-like object, optional
+            The crystal vector to use for one of the two shifting vectors.
+            Included here for those wishing to override the values set during
+            class initialization.
+        faultpos_rel : float, optional
+            The position to place the slip plane within the system given as a
+            relative coordinate along the out-of-plane direction.  Included
+            here for those wishing to override the value set when surface()
+            was called.  faultpos_rel and faultpos_cart cannot both be given.
+        faultpos_cart : float, optional
+            The position to place the slip plane within the system given as a
+            Cartesian coordinate along the out-of-plane direction.  Included
+            here for those wishing to override the value set when surface()
+            was called.  faultpos_rel and faultpos_cart cannot both be given.
+        
+        Yields
+        ------
+        a1 : float
+            The a1 fractional coordinate of a1vect. 
+        a2 : float
+            The a2 fractional coordinate of a2vect. 
+        atomman.System
+            The fault configuration associated with the a1, a2 shift.
+        """
+        # Update uvws and faultpos if given
+        if a1vect_uvw is not None:
+            self.a1vect_uvw = a1vect_uvw
+        if a2vect_uvw is not None:
+            self.a2vect_uvw = a2vect_uvw
+        if faultpos_cart is not None:
+            if faultpos_rel is not None:
+                raise ValueError('faultpos_rel and faultpos_cart cannot both be given')
+            self.faultpos_cart = faultpos_cart
+        elif faultpos_rel is not None:
+            self.faultpos_rel = faultpos_rel
+
+        if num_a1 is None:
+            num_a1 = 1
+        if num_a2 is None:
+            num_a2 = 1
+
+        # Construct mesh of regular points
+        a1s, a2s = np.meshgrid(np.linspace(0, 1, num_a1, endpoint=False),
+                               np.linspace(0, 1, num_a2, endpoint=False))
+
+        for a1, a2 in zip(a1s.flat, a2s.flat):
+            yield a1, a2, self.fault(a1=a1, a2=a2, outofplane=outofplane,
+                                     minimum_r=minimum_r)