emmet 2018.6.7

# Emmet

Emmet的目的是从计算材料计算的输出中“构建”材料属性的集合。目前，Emmet的有效目的是从[VASP](http://vasp.at)电子结构计算中提取输出，构建MongoDB集合，以支持[Materials Project](https://materialsproject.org)网站及其应用。

Emmet使用[Maggma](https://github.com/materialsproject/maggma)，这是我们更通用的聚合框架，它抽象了背后的机械操作：Maggma提供我们的`Builder`类和对`Stores`的通用接口，这些可以是MongoDB集合或纯JSON文件。

构建器`Builder`接收`source`存储库，处理该存储库中的项目，然后将结果构建到`target`存储库。

为了便于调试，Emmet中的数据流向仅有一个方向：这意味着每个存储库只能由特定的构建器构建，之后不会被后续的构建器修改。

构建器被设计为定期和自动运行：因此，存储库有一个“最后更新”过滤器（`lu_filter`），这样我们只尝试处理存储库中的新条目。

Emmet目前主要是内部材料项目工具，如果您正在阅读这篇文章，那么您可能刚刚加入该小组，在这种情况下：欢迎！:-)

## 目录

* [安装](#installation)
* [运行构建器](#running-a-builder)
* [编写新的构建器](#writing-a-new-builder)
* [VASP构建器](#vasp-builders)
* [MaterialsBuilder](#materialsbuilder)
* [ThermoBuilder](#thermobuilder)
* [ElasticBuilder](#elasticbuilder)
* [衍射构建器](#diffraction-builder)
* [拓扑构建器](#topology-builder)


## 安装

Emmet位于PyPI，因此`pip install emmet`应该可以工作。然而，它目前正处于非常活跃的开发中，因此目前建议进行可编辑的安装

```bash
pip install -e git+git@github.com:materialsproject/emmet.git#egg=emmet --src .
```

## 运行构建器

以下是一个运行MaterialsBuilder的示例脚本。根据需要替换数据库信息（此示例假设运行在本地的`test`数据库上，其中有一个预先填充的`tasks`集合，工作目录中有`mat.json`）。

```python
#!/usr/bin/env python

from maggma.runner import Runner
from maggma.stores import MongoStore, JSONStore
from emmet.vasp.builders.materials import MaterialsBuilder
from emmet.vasp.builders.thermo import ThermoBuilder

tasks_store = MongoStore(database="test",
collection_name="materials",
host="localhost",
port=27017,
lu_field="last_updated")
materials_settings_store = JSONStore("mat.json")
materials_store = MongoStore(database="test",
collection_name="tasks",
host="localhost",
port=27017)

materials_builder = MaterialsBuilder(tasks_store,
materials_settings_store,
materials_store,
lu_field="last_updated")

runner = Runner([materials_builder])

runner.run()

```

请注意正确设置`lu_field`：这是构建器用来查找文档上次更新时间并因此构建哪些新文档的关键。此字段默认不存在于MongoDB中。

要运行多个构建器，请添加

```python
thermo_store = MongoStore(database="test",
collection="thermo",
host="localhost",
port=27017)

thermo_builder = ThermoBuilder(materials_store,
thermo_store)
```

并将`runner = Runner([materials_builder])`更改为`runner = Runner([materials_builder, thermo_builder])`。

构建器的列表可以以任何顺序提供：它们的依赖关系将被智能解析，`Runner`将按正确的顺序运行构建器，并在系统支持的情况下并行运行。

## 编写新的构建器

从`Builder`基类派生子类并实现以下方法

* `get_items()` – 获取要处理的项目，例如，通过在源上运行查询的结果
* `process_item()` – 对每个项目执行某些操作，例如计算衍射图案
* `update_targets()` – 使用处理后的数据更新目标
* `finalize()` – 可选，执行任何最终的清理操作（关闭数据库连接等，基类可以处理此操作）

`DiffractionBuilder`(https://github.com/materialsproject/emmet/blob/master/emmet/vasp/builders/diffraction.py)是一个很好的简单构建器，可以作为起点来复制。

## VASP构建器

所有VASP构建器都操作于一个`tasks`存储库，该存储库由[Atomate的VaspDrone](https://pythonhosted.org/atomate/atomate.vasp.html#atomate.vasp.drones.VaspDrone)从任何VASP计算文件夹中解析而来。一旦创建了`tasks`存储库，Emmet的构建器就会接管。


### MaterialsBuilder

**来源** `tasks`（通常是 `tasks` 集合）、`material_settings`（通常是 `[mat.json](vasp/builders/mat.json)`）、`snls`（可选）

**目标** `materials`（通常是 `materials` 集合）

##### MaterialsBuilder 的功能

1. 只筛选出成功完成的任务。

2. 将任务分组到相同的结构。

结构匹配首先只选择具有相同化学公式的材料，然后使用 pymatgen 的 `StructureMatcher` 进行对称性分析。

3. 对于每个属性，根据预期能更准确预测该属性的任务的顺序对给定结构的任务进行排序（例如，来自能带结构计算的带隙比来自通用计算的带隙排序更高）。然后将此值选为该属性的规范值。

`task_type` 已确定，并来自任务存储，排序在 `[mat.json](vasp/builders/mat.json)` 中指定。不尝试对同一 `task_type` 的任务进行排序；在这种情况下，假定最近的计算具有优先权。

4. *(可选)* [结构符号语言](http://pymatgen.org/pymatgen.matproj.snl.html#pymatgen.matproj.snl.StructureNL)（或 'SNLs'）为在材料项目中捆绑结构及其元数据（例如，来自结构的 bibtex 引用）提供了一种方法。这将查找是否存在现有的 SNL(s) 用于该结构，并相应地分配 SNL。

### ThermoBuilder

**来源** `materials`

**目标** `thermo`

##### ThermoBuilder 的功能

1. 将材料分组到相同的化学系统（即，晶体结构包含相同元素的材料）。

2. 过滤掉不能直接相互比较的材料，例如，它们被不同的方法计算，其总能量处于不同的尺度。

默认情况下，这是通过在 pymatgen 中使用 `[MaterialsProjectCompatibility('Advanced')](http://pymatgen.org/pymatgen.entries.compatibility.html#pymatgen.entries.compatibility.MaterialsProjectCompatibility)` 实现的，它根据存在的元素智能地混合 GGA 和 GGA+U 计算，并对总能量进行适当的校正。

3. 使用 pymatgen 的 `[phasediagram](http://pymatgen.org/pymatgen.phasediagram.html)` 包计算每个材料的 [能量以上壳](https://materialsproject.org/wiki/index.php/Glossary_of_Terms#Energetics) 和，如果材料是不稳定的，其分解路径。

### ElasticBuilder

**来源** `materials`

**目标** `elastic`

##### ElasticBuilder 的功能

1. 从材料中选择一个初始结构
2. 从材料中找到此初始结构的变形实例，并计算变形矩阵
3. 如果找到 6 个独立的变形，则使用 pymatgen 的 `[ElasticTensor](http://pymatgen.org/pymatgen.analysis.elasticity.elastic.html#pymatgen.analysis.elasticity.elastic.ElasticTensor)` 计算弹性张量

### Diffraction Builder

**来源** `materials`、`xrd_settings`（通常是 `[xrd.json](vasp/builders/xrd.json)`）

**目标** `diffraction`

##### DiffractionBuilder 的功能

1. 对于每个结构，计算其在各种 X 射线靶（在 `[xrd.json](vasp/builders/xrd.json)` 中指定）的理想 X 射线衍射图案


### Topology Builder

**来源** `tasks`、`materials`

**目标** `toplogy`、`bader`

##### TopologyBuilder 的功能

1. 对于材料中的每个结构，使用多种方法（pymatgen的局部环境和critic2的原子电荷密度总和）从材料的晶体结构中计算化学键。

2. 然后找到与静态计算对应的任务。

3. 如果存在`AECCAR0`、`AECCAR2`、`CHGCAR`，则尝试使用critic2找到化学键信息，并执行单独存储的Bader分析。