来源：http://nupic.docs.numenta.org/stable/guides/swarming/running.html#advanced-usage
https://github.com/numenta/nupic/tree/master/src/nupic/swarming
https://github.com/numenta/nupic/blob/master/scripts/run_swarm.py
0 背景
此文档包含配置和运行swarms的详细说明。请参阅文档Swarming算法来描述底层的Swarming算法。
群集是为给定数据集自动确定最佳模型的过程。我们所说的“最佳”，是指最精确地产生所需输出的模型。群集计算哪些可选组件应该进入模型(编码器、空间池、时间记忆、分类器等，encoders, spatial pooler, temporal memory, classifier)，以及每个组件使用的最佳参数值。
我们计划用一个更通用的参数搜索库替换当前的群集库。这个代码库目前没有维护。我们目前没有API文档。
当你运行一个蜂群时，你提供以下信息:
1、用于优化的数据集(包含输入和期望输出的.csv文件)；
2、数据集的哪个字段(列)作为模型的输入和它们的数据类型；
3、在将输入记录输入模型(例如“aggregate hourly”)之前，需要聚合多少输入记录(或根本不需要)；
4、你想要完成的任务(例如"提前4步预测")；
5、用于评估模型有效性的可选自定义错误度量；
群的输出是一个OPF(在线预测框架)的格式description.py 文本文件，它完全描述了模型的组件及其参数。这个description.py文件可以在OPF中实例化，并与您希望的任何其他数据集运行。
一、先决条件
为了尽可能快地找到最佳模型，swarming可以利用在同一台机器上并发运行的多个进程。您可以告诉swarming工具通过命令行选项可以使用多少进程。根据您正在运行的机器(可用的内核和内存)，您可能会选择一个低为1或高达32的高端机器上的值。
MySQL数据库是每个工作进程之间的协调逻辑的一部分，因此，为了运行，swarming需要凭据到MySQL数据库。默认情况是使用托管在“localhost”上的数据库，使用“root”用户名和一个空密码(当您第一次在机器上安装MySQL时，这些是它创建的默认凭据)。如果您希望使用不同的数据库实例、名称或密码，请编辑“$NUPIC/ NUPIC/ support/nupic-default.xml”配置文件。您可以运行以下简单的测试脚本，以验证您的MySQL设置是否与NuPIC兼容:
python $NUPIC/examples/swarm/test_db.py
二、例子
要运行一个示例集群，执行以下命令行(假设您当前的目录是nupic repo的根)。这将会启动一个使用4个工人进程的蜂群:
$NUPIC/scripts/run_swarm.py $NUPIC/examples/swarm/simple/search_def.json --maxWorkers=4
当集群运行时，您将看到一些打印到stdout的进度消息。例如:
44modelsfinished[success:44;EOF:44;stopped:0;killed:0;error:0;orphaned:0;unknown:0]
一旦它完成(对于这个特殊的例子，在高端笔记本电脑上花费大约30秒)，它将打印一个总结信息，描述找到的最佳模型。例如:
BestresultsontheoptimizationmetricmultiStepBestPredictions:multiStep:errorMetric='altMAPE':steps=[1]:window=1000:field=consumption(maximize=False):[18]Experiment_GrokModelInfo(jobID=1104,modelID=17507,status=completed,completionReason=eof,updateCounter=7,numRecords=25)(modelParams|sensorParams|encoders|timestamp_timeOfDay:radius_3.375.modelParams|clParams|alpha_0.075025.modelParams|tpParams|minThreshold_11.modelParams|tpParams|activationThreshold_15.modelParams|tpParams|pamLength_4.modelParams|sensorParams|encoders|_classifierInput|n_398.modelParams|inferenceType_NontemporalMultiStep.modelParams|spParams|synPermInactiveDec_0.07625):multiStepBestPredictions:multiStep:errorMetric='altMAPE':steps=[1]:window=1000:field=consumption:25.1044742329TotalnumberofRecordsprocessed:1625Totalwalltimeforallmodels:100Generatingdescriptionfilesfortop1models...Generatingdescriptionfileformodel17507at/Users/me/Projects/Numenta/nupic/examples/swarm/simple/model_0Reportcsvsavedin/Users/me/Projects/Numenta/nupic/examples/swarm/simple/search_def_Report.csvElapsedtime(h:mm:ss):0:00:33
除了打印到stdout的信息之外，run_swarm还会在examples/swarm/simple中生成以下文件:
description.py:这是一个OPF描述文件，为您正在创建的模型类型设置默认的模型参数。
permutations.py:这是一个swarming排列文件，它定义了在集群中使用的搜索空间的范围。例如，它包含每个参数的最小值和最大允许值。除非您想要执行更高级的群集(参见下面)，否则您可以忽略此文件。
model_0/description.py:这是一个OPF描述文件，它覆盖了上面 description.py描述的通过swarming发现的最好的特定参数。这个描述文件可以使用run_opf_experiment.py运行。
model_0/params.csv:包含为这个最佳模型选择的参数值的csv文件。这仅供参考。
model_0/model_params.py:模型参数，可用于通过ModelFactory手动创建模型。
search_def_Report.csv:这是一个电子表格，它列出了被评估为集群的一部分的每个模型的信息。对于每个模型，它都有使用的参数，以及在评估的每个错误指标上生成的模型的结果。
注意:当运行集群时，如果您遇到了一个错误，例如“logger无法找到处理程序……”这可能是一个MySQL设置问题。您可以使用上面的脚本进行检查。
三、由蜂群发现的运行模型
群的结果是一个具有最佳发现参数的模型。目录model_0包含完整的细节。如果您现在想在附加数据上自己运行这个最佳模型，请发出以下命令:
python $NUPIC/scripts/run_opf_experiment.py examples/swarm/simple/model_0/
四、以编程方式运行一个群
您不必使用run_opf_experiment.py命令行脚本运行模型。它也可以通过编程方式完成。运行集群可以通过导入permutations_runner来完成，如下所示:
importnupic.swarming.permutations_runnerswarm_config={}# complete swarm config heremodel_params=permutations_runner.runWithConfig(swarm_config,{'maxWorkers':8,'overwrite':True})model=ModelFactory.create(model_params)
它们可以作为python字典创建，而不是将群集配置放入JSON文件中。一旦群体完成，它将会是一个代表最佳模型参数的对象。这个配置可以使用由蜂群产生的模型参数启动nupic。
五、指定一个群
有两个主要的输入需要定义一个蜂群:
蜂群的描述。这描述了创建的模型类型以及关于输入数据的一些元信息。
一个数据文件。这是一个包含输入数据和模型所需输出的csv文件。
六、Swarm描述
在“examples/swarm/simple/search_def.json”中可以看到第一个例子。这个json文件中包含了swarm描述文件，你也可以选择让run_swarm使用permutations.py来运行。
这个具体的JSON文件给你了一个能做什么的总览。swarmJSON文件中所能包含的所有可能设置和值在其它wiki页面中描述，这个JSON文件的框架能在src/nupic/swarming/exp_generator/experimentDescriptionSchema.json中被找到。
includedFields：该字段描述了.csv文件中那个字段被作为模型的输入，以及每个字段的数据类型。默认情况下，swarm不会将一个字段作为一个模型可能的输入，除非在这个字段中列出来。
streamDef：描述输入文件的位置，以及你希望对这些数据进行聚合的数量。
inferenceType：该字段描述了你希望创建的模型类型。对于特定例子，我们创建一个预测模型能够提前预测多步，我们将这个值设定为“MultiStep”。
inferenceArgs:针对MultiStep模型包含了你预测的提前步骤数量以及预测字段的名称（输入.csv文件中包含的预测字段）。在这个例子中我们将提前1步预测"consumption"。
iterationCount：该字段给出了输入到模型中的聚合记录的最大数量。
swarmSize：控制了群体运行。“small”, “medium”, and “large”。
七、数据文件
streamDef配置对象中的每个流对象都应该包含一个源值，该源值是输入CSV数据文件的路径。这可能是一个绝对的或相对的路径，但必须从文件://描述符开始。
八、3万英尺的鸟瞰过程
通过在数据集上尝试一堆不同的模型来进行工作，最终选择并输出产生最低错误分数的模型。对于预测模型来说，误差分数是预测与实际数据的距离的度量。在本文档中使用的示例中，我们试图提前预测1步，因此错误分数是模型预测与下一个记录中到达模型的实际值之间的距离的度量。错误分数在每条记录之后更新，并作为滚动平均值计算到模型看到的最后N条记录上(默认情况是使用最后1000条记录)。
一个典型的群体可能正在搜索一个相当大的参数空间。例如，在数据文件中可能有5个可能的输入字段可供选择，模型有12个不同的参数，每个参数的可能值范围都很大。对该空间的穷尽性搜索是惊人地昂贵的，所以对其搜索进行智能的尝试是明智的。
在内部，群集使用一种类似粒子群优化的方法来搜索模型的标量参数。有关群集算法的深入描述，请参见群集算法。粗略地说，首先对空间进行粗次采样，然后在每个“位置”(粒子)上运行一个模型。一旦在每个位置对错误进行评估，每个粒子都被允许移动到一个不同的位置，并选择新的位置，这样每一个粒子都倾向于被其他粒子所吸引到目前为止最小错误的位置上。
群集还能计算出哪些输入字段在做出良好预测时是有用的。如果一个字段是无用的，则它不包含在最终模型中。为此，它首先尝试每个字段。从评估中找到的最好的字段集，它构建两个字段的组合，然后再构建三个字段，等等，直到错误分数停止改进。
对于一个典型的数据集，集群可能需要评估10个或100个模型，以便确定最佳的参数集。如果您在机器上只运行一个进程，那么一次只能计算一个模型。你运行的进程越多，可以同时评估的模型就越多，群的完成速度也就越快。
九、一个简单的例子
这里有一个简单的示例，说明您需要在自己的数据集上运行群集。假设您有一个新的数据集，其中前几行如下:
字段名与以前不同，并且缺少体育馆列。创建一个新的目录~/myswarm和一个子目录~/myswarm/data。examples/swarm/simple/search_def.json复制到~ / myswarm。将数据文件复制到~/myswarm/data中。
现在需要编辑.json文件，以包含新的字段信息和新的文件名。字段名在几个地方指定。下面更改的search_def.json现在应该可以工作了(已标记的更改):
现在输入：
十 高级用法
本节介绍一些高级主题:从permutations.py文件运行一个集群，使用自定义错误度量，并在Docker容器中运行一个集群。
1、使用permutations.py文件运行一个群集
如上所述，从头创建群集的最简单方法是提供一个JSON文件，其中包含高级的群集描述。当你以这种方式使用run_swarm工具时，在实际上运行swarm之前，swarm工具会在内部执行以下操作:
（1）通过ExpGenerator运行JSON文件，生成permutations.py文件和description.py文件。
（2）使用permutations.py文件指导群的参数搜索空间。
ExpGenerator为模型创建置换选项(搜索空间)，并将它们写入permutations.py文件。如果您想修改这些选项，您可以告诉run_swarm直接使用自定义的permutations.py文件。为此，您可以提供.py文件名参数，而不是.json文件名:
(如果您还没有permutations.py文件，可以使用JSON文件调用run_swarm，它将为您生成permutations.py文件和description.py文件)。
当您使用permutations.py文件调用run_swarm时，它还假设可以在与permutations.py相同的目录中找到description.py文件。description.py包含整个OPF模型描述，带有一些默认参数值。随着集群的运行，从permutations.py定义的参数空间中选择的各种不同的参数值被插入到这个description.py框架中，以便生成每个模型。
在permutationspy文件中可以做的一些事情是:
更改参数的可能值范围；
从description.py中添加额外的参数，以便进行仔细的分析；
硬编码特定的参数值，这些参数值通常会被覆盖。（硬编码表示不被覆盖？？？？）
2、使用自定义错误指标
默认情况下，您的模型的准确度将使用MAPE(平均平均误差百分比)误差指标来评估模型在过去1000条记录中所看到的误差。为了计算这个，OPF取最后1000条记录的绝对误差(abs(预测-实际)的平均值，除以最后1000条记录的平均实际值。
如果你想要在不同数量的记录下评估你的模型的精度,或者使用一个完全不同的误差度量,你可以通过群JSON描述文件“metricWindow”和“customErrorMetric”部分实现，（或者如果您正在使用permutations.py运行群，通过编辑description.py文件实现)。
如果您只想更改评估默认错误度量的记录的数量，请在JSON文件中包含“metricWindow”部分:
如果您希望更改错误度量本身，请包含“customErrorMetric”部分。/examples/swarm/simple/search_def_custom_error.json展示了如何做到这一点。下面是这个例子的摘录:
这个特定的示例展示了如何生成一个误差度量，该度量计算预测与实际之间的误差的平方，并在最近的500条记录中进行计算。
对于更复杂的错误函数，可以编写一个利用历史值和中间变量的函数。因为自定义错误度量函数是在“沙箱”中计算的，所以需要使用特殊的结构来存储和访问这些变量。例如，如果您想评估以下误差度量:
您将提供的自定义错误函数代码如下所示(这只是为了让您对可以完成的工作有一个了解，对完整的自定义错误度量语法的解释超出了本文的范围)。
当您将上述函数嵌入到JSON文件中时，您将需要转义任何特殊字符。最简单的方法是通过python的string encode()方法运行文本:
对上述函数进行编码后，JSON文件如下:
3、用Docker管理蜂群
http://nupic.docs.numenta.org/stable/guides/swarming/running.html#advanced-usage
http://nupic.docs.numenta.org/stable/quick-start/algorithms.html#getting-predictions
https://github.com/numenta/nupic/blob/master/scripts/run_swarm.py
https://github.com/numenta/nupic/tree/master/examples/swarm