tinker-engine

示例文档

查看示例以开始使用Tinker Engine。

开发者设置

构建Tinker Engine

在本地构建Tinker Engine的最简单方法是使用poetry。这些步骤将创建一个虚拟环境，在其中构建和安装Tinker Engine，并使其可用于使用。

1. 克隆此存储库。
2. 在 tinker-engine 目录中，使用 poetry install 安装依赖项。
3. 使用 poetry shell 激活虚拟环境。
4. 运行Tinker Engine以确保其正常工作： tinker --help。

运行Tinker Engine

在 examples/helloworld/helloworld.py 中有一个示例协议定义。您可以使用以下方式与Tinker Engine一起使用它

$ tinker -c examples/helloworld/helloworld.yaml examples/helloworld/helloworld.py

由于Tinker Engine只在其提供的入口点中找到单个协议，它将自动实例化并运行找到的协议。但您也可以列出它所知的协议，如下所示

$ tinker -c examples/helloworld.yaml examples/helloworld.py --list-protocols

其他示例

在 examples 目录中包含几个协议和配置，您可以使用它们来探索Tinker Engine的工作方式。

配置指令

在 examples/config 目录中包含示例，展示了各种配置指令，使用一个简单的协议打印传递给它的配置

$ tinker -c examples/config/iterate.yaml examples/config/show_config.py

演示了如何组合性地使用 iterate 指令

$ tinker -c examples/config/iterate_nested.yaml examples/config/show_config.py

演示了将一个 iterate 指令嵌套在另一个指令中的语义

当不需要迭代时，一个“纯”配置文件将按预期工作

$ tinker -c examples/config/vanilla.yaml examples/config/show_config.py

SMQTK指令

examples/smqtk 文件夹包含 SMQTK 实现的示例、SMQTK 配置文件以及用于显示 SMQTK 实例化的特定协议。

从根目录，我们可以测试 SMQTK 支持。

$ SMQTK_PLUGIN_PATH=examples.smqtk.hello_smqtk tinker  -c examples/smqtk/hello_smqtk.yaml examples/smqtk/show_smqtk.py

命令行文档

usage: tinker [-h] -c CONFIG [--list-protocols] [--list-algorithms]
              [--log-file LOG_FILE] [--log-level LOG_LEVEL]
              protocol_file [protocol_file ...]

positional arguments:
  protocol_file         python file defining protocols/algorithms/etc.

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        config file
  --list-protocols      Print the available protocols
  --list-algorithms     Print the available algorithms
  --log-file LOG_FILE   Path to log file
  --log-level LOG_LEVEL
                        Logging level

通常，您会使用 tinker 工具，通过提供配置文件并使用 -c 选项，以及至少一个作为位置参数列出的 protocol_file 来使用它。Tinker 引擎将读取配置文件，并使用它来实例化在某个 protocol_file 中定义的 Protocol 对象。

--log-file 选项设置用于日志文件的文件名；默认情况下，它将使用运行计算机的主机名和当前时间命名的文件。

--list-protcols 和 --list-algorithms 选项是用于诊断的选项，以显示 Tinker 引擎检测到的内容。这些选项将分别打印出 Tinker 引擎找到的所有 Protocol 和 Algorithm 对象。这些是在运行 Tinker 引擎时可供使用的对象。

在 PYPI 上发布

Tinker 使用 github actions 在 pypi 上发布包。当将 semver 标签推送到 tinker 时，此操作将被触发。

我们支持以下版本格式 <major>.<minor>.<patch> 和 <major>.<minor>.<patch>-alpha.<alpha-version> 用于标签。要在 pypi 上发布包，标签必须与 pyproject.toml 中维护的版本相匹配。这作为工作流程中的一个强制检查来实施。Poetry 提供了通过 cli 查询和升级版本的 支持。有关更多详细信息，请参阅 version。

因此，要在 pypi 上发布 tinker，请使用以下命令

1. 使用 poetry version <version_rule> 升级 pyproject.toml 中的版本。
2. 使用 poetry version --short 确定将用于标签的版本。
3. 使用以下命令生成和推送标签

    git tag <package-version>
    git push origin --tags
   

致谢

本材料是基于美国国防部高级研究计划局（DARPA）在合同编号 HR001120C0055 下支持的工作以及由 DARPA 赞助的研究（协议编号 FA8750-19-1-0504）。本材料中表达的任何观点、发现、结论或建议都是作者的观点，不一定反映 DARPA 的观点。美国政府有权复制和分发用于政府目的的副本，尽管上面有版权声明。

忽略以下所有内容

入门

此存储库包含 tinker-engine 包的开发版本。要安装它，请确保您位于所需的 Python 环境中（例如，通过创建虚拟环境），进入此存储库的顶层目录，并使用 pip。

pip install -e .

完成此操作后，您可以使用以下命令使用 Tinker 引擎执行协议

tinker protocol_file

protocol_file 是 python 协议文件的路径和名称。项目管理员应将协议脚本提供给研究人员以供本地开发使用。protocol_file 可以是绝对文件路径，也可以是从当前工作目录到协议文件的路径。Tinker 引擎可以从任何位置执行，但建议从算法目录的根目录运行。

如果需要从算法目录根目录之外的位置运行 Tinker 引擎，应使用 -a 参数提供算法目录根路径。

tinker protocol_file -a alogorithms_path

Tinker 引擎还可以使用不同的 harness 接口运行。使用 -l 标志列出可用的接口。默认情况下，Tinker 引擎使用 Tinker Engine 提供的 LocalInterface。可以使用 -i <interface name> 参数选择其他接口。也可以使用用户定义的接口，但必须从 Harness 基类派生，并且应放在与协议文件相同的文件夹中。如果一切设置正确，-l 标志还将打印出任何可用的用户定义接口的名称。

运行 Learn

首先，安装 Tinker Engine（请参阅上方说明）。接下来，查看 Learn 仓库。使用 pip 命令安装 Learn 包：如果 tinker-engine 和 learn 仓库位于相邻目录，并且您位于 tinker-engine 的顶级目录中，则适当的命令将是 pip install -e ../learn。

然后，您需要下载所有数据集并遵循以下说明：[链接](https://gitlab.lollllz.com/lwll/dataset_prep)。确保 lwll_datasets 目录位于您的当前目录。

要运行 learn 协议，按如下方式调用 tinker 命令

tinker ../learn/learn/protocol/learn_protocol.py -a ../learn/learn/algorithms

系统设计

Tinker Engine 由三部分组成。Tinker Engine 本身安装得可以执行系统上任何期望的位置。第二部分是协议和可选接口。协议由项目团队编写以满足整个项目的要求。这是一个 Python 脚本，以期望的方式执行系统的所有部分。项目团队还可能希望包括更简单的协议，这些协议一次只练习一个算法。这对于研究人员开发算法很有用。此外，如果标准的本地接口测试平台不足以满足项目需求，项目团队可以定义一个替代接口，只要它从 Harness 类继承。第三部分是算法。系统的这三个部分不需要在同一位置。算法的唯一要求是它们都位于同一根目录下，并且任何用户定义的接口都必须与协议文件在同一文件夹中。

系统的基本设计支持用户的两层体系结构。第一层是项目管理员。在这一级别，实验协议得到建立和规范。为了使这项工作更容易，最终协议代码是用 Python 编写的，并且对它的工作方式几乎没有限制。Tinker Engine 本身主要提供用户编写协议文件的支持结构。该系统图如下

在这个框架下，执行的开始是在 main.py 中，它从给定的协议 Python 文件中定位、准备和加载协议。它还加载请求的接口并将其提供给协议。文件名由最终用户通过命令行参数提供，协议文件中类的名称无关紧要（它将根据其名称加载）。然后执行传递给协议的 run_protocol 函数。用户协议应继承自 tinker.BaseProtocol。BaseProtocol 提供访问 get_algorithm 函数的权限，该函数将定位并动态加载请求的算法。当协议需要将执行传递给特定算法时，它应该调用该算法的 "execute" 函数。该函数的一个参数提供了一个 step_description，它表示算法应执行的处理模式。为了便于这种行为，每个算法类都必须直接从 tinker.BaseAlgorithm 继承，或者从从 BaseAlgorithm 继承的适配器类继承。与协议文件一样，算法文件中类的名称被忽略，无论其名称如何，都会加载该类。

在实现算法时，必须提供 "requirements.txt" 文件，以便我们可以了解算法的依赖关系。一个示例依赖文件看起来如下

torch>=1.3.0
torchvision>=0.3.0
numpy>=1.16.4
scikit-learn>=0.21.1
scipy>=1.2.1
ubelt>=0.8.7

支持声明和免责声明

本材料是基于由美国国防部高级研究计划局（DARPA）资助的工作，合同编号为 HR001120C0055。本材料中表达的意见、发现和结论或建议是作者的观点，不一定反映 DARPA 的观点。

本材料是基于由 DARPA 赞助的研究，协议编号为 FA8750-19-1-0504。美国政府有权为政府目的复制和分发副本，尽管其中可能有版权声明。