Python模型类
模型类
- class pysd.py_backend.model.Model(py_model_file, data_files, data_files_encoding, initialize, missing_values)[源代码]
Model类实现系统的有状态表示。它从Macro类继承方法来集成模型以及访问和修改模型组件。它还包含运行模型的主要方法。
模型对象将使用从转换的Python模型文件中绘制的组件创建。
- 参数:
py_model_file (str or pathlib.Path) -- 已转换为Python格式的模型文件夹。
data_files (dict or list or str or None) -- 包含键、文件名和变量的字典，以从那里加载数据。或者要搜索数据的名称列表或文件名称。仅适用于TabData类型对象，并且有必要提供它。默认为无。
initialize (bool) -- 如果为False，则加载模型时不会初始化。默认为True。
missing_values (str ("warning", "error", "ignore", "keep") (optional)) -- 如何处理缺失的值。如果“warning”（默认）显示警告消息并内插值。如果“raise”引发错误。如果“忽略”则插入值而不显示任何内容。如果选择“keep”，它将保留缺失的值，此选项可能会导致集成失败，但它可以用于检查数据的质量。
- run(params=None, return_columns=None, return_timestamps=None, initial_condition='original', final_time=None, time_step=None, saveper=None, reload=False, progress=False, flatten_output=True, cache_output=True, output_file=None)[源代码]
模拟模型随时间推移的行为。返回pandas绘图框，其中时间戳为行，模型元素为列。更详细的信息和使用示例，请访问 Getting Started .
- 参数:
params (dict (optional)) -- 关键字是模型组件名称的字符串。值是数字或Pandas系列。数字值表示模型积分上的常数。时间序列将被插值以提供时变输入。有关更多信息，请查看
pysd.py_backend.model.Macro.set_components().return_timestamps (list, numeric, ndarray (1D) (optional)) -- 模型执行中返回状态信息的时间戳。复制到模型文件指定的时间步。
return_columns (list, 'step' or None (optional)) -- 字符串模型组件名称列表，返回的字符串框架会有对应的列。如果是'step'，则只返回带有缓存step的变量。如果为None，则返回具有缓存步骤和运行的变量。默认为无。
initial_condition (str or (float, dict) (optional)) -- 开始时间以及该开始时间的系统状态（所有股票的价值）。“original”或“o”使用模型文件指定的初始条件。“当前”或“c”使用上次执行后模型的状态。其他字符串对象从具有给定名称的pickle文件加载初始条件。（float，dict）tuple允许用户指定库存（有状态）对象的开始时间（float）和初始值（可能是部分）字典。默认为“原始”。有关更多信息，请查看
pysd.py_backend.model.Model.set_initial_condition()final_time (float or None) -- 模拟的最后时间。如果是float，则给定的值将用于计算return_timestamps（如果未给定）并作为最终时间。如果为None，则return_timestamps的最后一个值将用作最终时间。默认为无。
time_step (float or None) -- 模拟的时间步。如果是浮动的，则给定的值将用于计算Return_timestamps（如果没有给出）和eSYS时间序列。如果无，将使用组件的默认值。默认为无。
saveper (float or None) -- 保存模拟步骤。如果是浮动的，则给定的值将用于计算Return_timestamps（如果没有给出）。如果无，将使用组件的默认值。默认为无。
reload (bool (optional)) -- 如果为True，则在进行更改之前从转换后的模型文件重新加载模型。默认为假。
progress (bool (optional)) -- 如果为True，则在集成期间将显示进度条。默认为假。
flatten_output (bool (optional)) -- 如果为True，一旦输出数据包被格式化，就会按照Vensim的命名将xarrays拆分为新列，以生成完全平坦的输出。默认为True。当在输出_文件参数中传递netCDF4文件路径时，将忽略此参数。
cache_output (bool (optional)) -- 如果为True，则输出变量的调用次数将增加1。如果输出变量仅被调用一次，这将有助于缓存它们。出于性能原因，如果时间步= saveper，则建议激活此功能，如果时间步<< saveper，则建议停用它。默认值为True。
output_file (str, pathlib.Path or None (optional)) -- 保存模拟结果的文件路径。目前支持CSV、tab和nc（netCDF4）文件。
示例
>>> model.run(params={'exogenous_constant': 42}) >>> model.run(params={'exogenous_variable': timeseries_input}) >>> model.run(return_timestamps=[1, 2, 3, 4, 10]) >>> model.run(return_timestamps=10) >>> model.run(return_timestamps=np.linspace(1, 10, 20)) >>> model.run(output_file="results.nc")
- set_stepper(output_obj, params=None, step_vars=[], return_columns=None, return_timestamps=None, initial_condition='original', final_time=None, time_step=None, saveper=None, cache_output=True)[源代码]
配置模型步进行为。使用示例可在 Advanced Usage .
- 参数:
output_obj (ModelOutput) -- 存储模拟结果的模型输出实例。
params (dict (optional)) -- 关键字是模型组件名称的字符串。值是数字或Pandas系列。数字值表示模型积分上的常数。时间序列将被插值以提供时变输入。
step_vars (list) -- 其值可能在一个或多个模拟步骤后更新的变量或参数名称列表。
return_columns (list, 'step' or None (optional)) -- 字符串模型组件名称列表，返回的字符串框架会有对应的列。如果是'step'，则只返回带有缓存step的变量。如果为None，则返回具有缓存步骤和运行的变量。默认为无。
return_timestamps (list, numeric, ndarray (1D) (optional)) -- 模型执行中返回状态信息的时间戳。复制到模型文件指定的时间步。
initial_condition (str or (float, dict) (optional)) -- 开始时间以及该开始时间的系统状态（所有股票的价值）。“original”或“o”使用模型文件指定的初始条件。“当前”或“c”使用上次执行后模型的状态。其他字符串对象从具有给定名称的pickle文件加载初始条件。（float，dict）tuple允许用户指定库存（有状态）对象的开始时间（float）和初始值（可能是部分）字典。默认为“原始”。
final_time (float or None) -- 模拟的最后时间。如果是float，则给定的值将用于计算return_timestamps（如果未给定）并作为最终时间。如果为None，则return_timestamps的最后一个值将用作最终时间。默认为无。
time_step (float or None) -- 模拟的时间步。如果是浮动的，则给定的值将用于计算Return_timestamps（如果没有给出）和eSYS时间序列。如果无，将使用组件的默认值。默认为无。
saveper (float or None) -- 保存模拟步骤。如果是浮动的，则给定的值将用于计算Return_timestamps（如果没有给出）。如果无，将使用组件的默认值。默认为无。
cache_output (bool (optional)) -- 如果为True，则输出变量的调用次数将增加1。如果输出变量仅被调用一次，这将有助于缓存它们。出于性能原因，如果时间步= saveper，则建议激活此功能，如果时间步<< saveper，则建议停用它。默认值为True。
- step(num_steps=1, step_vars={})[源代码]
运行模型步骤。首先更新模型变量（可选），然后运行任意数量的模型步骤。要在一个或多个步骤后收集输出，请使用建模输出类的collect方法。使用示例可在 Advanced Usage
- select_submodel(vars=[], modules=[], exogenous_components={}, inplace=True)[源代码]
从原始模型中选择子模型。选择子模型后，仅计算集成该子模型所需的有状态对象。使用示例可在 Advanced Usage .
- 参数:
vars (set or list of strings (optional)) -- 要包含在新子模型中的变量。如果仅通过模块名称选择子模型，则可以是空列表。默认为空列表。
modules (set or list of strings (optional)) -- 新子模型中包含的模块。如果仅通过变量名称选择子模型，则可以是空列表。默认为空列表。可以通过传递不带.py的路径来选择完整模块或子模块，例如：“view_1/submodule1”。
exogenous_components (dictionary of parameters (optional)) -- 用于修复运行所选子模型所需的模型变量的外部值。externative_components应该作为字典传递，与set_components方法相同。默认情况下，它是空的dict，并且所需的外部组件将被设置为numpy.nan值。
inplace (bool (optional)) -- 如果为True，它将修改当前对象并返回无。如果为假，它将创建模型的副本并返回它，保持原始模型不变。默认为True。
- 返回:
如果inplace=False，它将返回原始模型的修改副本。
- 返回类型:
None or pysd.py_backend.model.Model
备注
只有当模型在转换过程中被拆分为不同的文件时，才能传递模块。
示例
>>> model.select_submodel( ... vars=["Room Temperature", "Teacup temperature"]) UserWarning: Selecting submodel, to run the full model again use model.reload()
>>> model.select_submodel( ... modules=["view_1", "view_2/subview_1"]) UserWarning: Selecting submodel, to run the full model again use model.reload() UserWarning: Exogenous components for the following variables are necessary but not given: initial_value_stock1, stock3
>>> model.select_submodel( ... vars=["stock3"], ... modules=["view_1", "view_2/subview_1"]) UserWarning: Selecting submodel, to run the full model again use model.reload() UserWarning: Exogenous components for the following variables are necessary but not given: initial_value_stock1, initial_value_stock3 Please, set them before running the model using set_components method...
>>> model.select_submodel( ... vars=["stock3"], ... modules=["view_1", "view_2/subview_1"], ... exogenous_components={ ... "initial_value_stock1": 3, ... "initial_value_stock3": 5}) UserWarning: Selecting submodel, to run the full model again use model.reload()
- get_dependencies(vars=[], modules=[])[源代码]
获取一组变量或模块的依赖项。
- 参数:
- 返回:
dependencies --附属数据对象。
- 返回类型:
pysd.py_backend.utils.Dependencies
备注
只有当模型在转换过程中被拆分为不同的文件时，才能传递模块。
示例
>>> print(model.get_dependencies( ... vars=["Room Temperature", "Teacup temperature"])) Selected variables (total 1): room_temperature, teacup_temperature Stateful objects integrated with the selected variables (total 1): _integ_teacup_temperature
>>> print(model.get_dependencies( ... modules=["view_1", "view_2/subview_1"])) Selected variables (total 4): var1, var2, stock1, delay1 Dependencies for initialization only (total 1): initial_value_stock1 Dependencies that may change over time (total 2): stock3 Stateful objects integrated with the selected variables (total 1): _integ_stock1, _delay_fixed_delay1
>>> print(model.get_dependencies( ... vars=["stock3"], ... modules=["view_1", "view_2/subview_1"])) Selected variables (total 4): var1, var2, stock1, stock3, delay1 Dependencies for initialization only (total 1): initial_value_stock1, initial_value_stock3 Stateful objects integrated with the selected variables (total 1): _integ_stock1, _integ_stock3, _delay_fixed_delay1
- copy(reload=False)[源代码]
创建当前模型的副本。
- 参数:
reload (bool (optional)) -- 如果为True，则模型将被复制，而不会对其应用任何更改，副本将简单地从转换后的文件中再次加载模型。这相当于做
pysd.load()有同样的论点。否则，它将应用与原始模型相同的更改并更新状态（忠实副本）。默认为假。
警告
复制函数将从文件加载新模型并对其应用相同的更改。如果这些更改中的任何一个已用引用模型中其他变量的函数替换了变量，则复制将无法正常工作，因为该函数仍然将引用原始模型中的变量，在这种情况下，应该重新定义该函数。
- set_initial_condition(initial_condition)[源代码]
设置集成的初始条件。
- 参数:
initial_condition (str or (float, dict) or pathlib.Path) -- 开始时间以及该开始时间的系统状态（所有股票的价值）。“original”或“o”使用模型文件指定的初始条件。“当前”或“c”使用上次执行后模型的状态。其他字符串对象从具有给定名称的pickle文件加载初始条件。（float，dict）tuple允许用户指定库存（有状态）对象的开始时间（float）和初始值（可能是部分）字典。
示例
>>> model.set_initial_condition('original') >>> model.set_initial_condition('current') >>> model.set_initial_condition('exported_pickle.pic') >>> model.set_initial_condition((10, {'teacup_temperature': 50}))
- export(file_name)[源代码]
将有状态值导出到pickle文件。
- 参数:
file_name (str or pathlib.Path) -- 要导出值的文件的名称。
- import_pickle(file_name)[源代码]
从pickle文件导入有状态值。
- 参数:
file_name (str or pathlib.Path) -- 要从中导入值的文件的名称。
参见
pysd.py_backend.model.Model.export_pickle()
宏类
- class pysd.py_backend.model.Macro(py_model_file, params=None, return_func=None, time=None, time_initialization=None, data_files=None, data_files_encoding=None, py_name=None)[源代码]
Macro类实现系统的有状态表示，并包含大多数用于访问和修改组件的方法。
当所讨论的实例还充当根模型对象（而不是另一个模型中的宏或子模型）时，它将添加方法来促进执行。
宏对象将使用从转换的Python模型文件中绘制的组件创建。
- 参数:
py_model_file (str or pathlib.Path) -- 已转换为Python格式的模型或宏的文件集。
params (dict or None (optional)) -- 宏参数的字典。默认为无。
return_func (str or None (optional)) -- 要从宏返回的函数的名称。默认为无。
time (components.Time or None (optional)) -- 整合的时间对象。如果无，将生成新的时间对象（对于模型），如果经过，将使用时间对象（对于宏）。默认为无。
time_initialization (callable or None) -- 是时候准备宏的时候了。默认为无。
data_files (dict or list or str or None) -- 包含键、文件名和加载数据的变量的字典。或者要搜索数据的名称列表或文件名称。仅适用于TabData类型对象，并且有必要提供它。默认为无。
py_name (str or None) -- 宏对象的名称。默认为无。
- property doc: <Mock name='mock.DataFrame' id='139859939967120'>
模型的文档。
- initialize_external_data(externals=None)[源代码]
卸载外部数据。
如果在外部参数中传递包含部分或所有模型外部数据的序列化值的netEDF文件的路径，则将从该文件加载这些。
为了获得从netEDF文件加载外部文件的全部性能提升，应该首先使用initialize=False来加载模型。
使用示例可在 Advanced Usage .
- 参数:
externals (str or pathlib.Path (optional)) -- 包含模型外部对象的netEDF文件的路径。
- 返回类型:
None
备注
要从netEDF文件加载外部文件，您需要安装可选依赖项 netCDF4 .
- serialize_externals(export_path='externals.nc', include_externals='all', exclude_externals=None)[源代码]
存储netEDF文件，其中包含所有模型外部对象的数据和元数据。
此方法对于具有大量外部输入的模型很有用，这些输入加载到内存中的速度较慢。输出后，生成的netEDF文件可以作为参数传递给initialize_externative_data方法。
变量的名称应该是模型中的变量（Python安全，没有 _ext_type_ 前面的字符串）。
使用示例可在 Advanced Usage .
- 参数:
export_path (str or pathlib.Path (optional)) -- 结果的路径 .nc 文件.
include_externals (list or str (optional)) -- 要输出到netEDF的外部对象。如果“全部”，则所有外部内容都被输出到 .nc 文件.该参数还接受包含电子表格文件名、外部变量名或两者组合的列表。如果传递电子表格文件路径，其中定义的所有外部对象都将包含在 .nc 文件.当前不支持电子表格选项卡名称，因为相同的选项卡名称可能会在不同的文件中使用。通过组合main_externals和exclude_externals（请参阅下面的描述）参数可以实现更好的定制。
exclude_externals (list or None (optional)) -- 阻止外部对象包含在输出的nc文件中。它接受变量名、电子表格文件或两者的组合。
- 返回类型:
None
备注
要运行此功能，您需要安装可选依赖项 netCDF4 .
- get_args(param)[源代码]
返回模型元素的参数。
示例
>>> model.get_args('birth_rate') >>> model.get_args('Birth Rate')
- get_coords(param)[源代码]
返回模型元素的坐标和尺寸。
- 参数:
param (str or func) -- 模型元素名称或函数。
- 返回:
(coords, dims) or None --元素的坐标和维度（如果有的话）。否则，返回无。
- 返回类型:
示例
>>> model.get_coords('birth_rate') >>> model.get_coords('Birth Rate')
- get_series_data(param)[源代码]
Returns the original values of a model lookup/data component.
- 参数:
param (str) -- 模型查找/数据元素名称。
- 返回:
value --具有第一维插值系列值的数组。
- 返回类型:
示例
>>> model['room_temperature'] >>> model['Room temperature']
- set_components(params)[源代码]
设置外生模型元素的值。元素值应该在函数调用中与字典一起传递。值可以是数字类型或pandas Series。系列将由积分器进行插值。
- 参数:
params (dict) -- 包含要修改的元素名称及其将采用的值的字典。如果传递的值是
float或xarray.DataArray(must与变量的维度兼容）。在这种情况下，变量将具有一个常数值，返回过去的值并在必要时广播到所有维度。如果pandas.Series传递时，该变量将为数据类型，并将使用模型的时间来内插以系列索引作为参考的结果。在这种情况下，系列“数据”也可以是float或xarray.DataArray，与常值一样。如果目标使用pysd.py_backend.lookups.Lookup对象，它将修改对象的值，以在被调用时使用原始参数。更详细的信息和使用示例，请访问 Getting Started . 为了编写更复杂的关系（可能包括或可能不包括其他模型变量），可以传递可调用的（例如函数），该可调用的参数与原始函数相同，并返回float或xarray.DataArray其维度与原始功能完全相同。更详细的信息和使用示例，请访问 Advanced Usage .
备注
该函数用于修改变量的值或方程，它无法与状态对象正常工作，例如Integ、DelayFixed.为了修改它们，需要手动进行，如果您有其他输入，建议修改这些输入。改变它们的初始值
pysd.py_backend.model.Model.set_initial_condition()方法可以使用。示例
>>> model.set_components({'birth_rate': 10}) >>> model.set_components({'Birth Rate': 10})
>>> br = pandas.Series(index=range(30), data=np.sin(range(30)) >>> model.set_components({'birth_rate': br})