跳到主要内容

容器

符号​

通用图标如下

Containers_image1.png

不同场景下画布对象图标详见数据组件章节

功能​

专门用于存储资源和实体的Dict格式特殊数据元素

要点​

提示
  • 容器本质格式为Dict[Str, Number]，如 {"ETH":20, "WBTC":1}
  • 资源操作时，容器固定搭配容器操作和操作链使用，建议结合相关内容理解。

理解“资源”​

容器中存储的资源可分为以下两类：

可生产消耗资源​

可以利用、交换、消费和再生产的同质品，支持多种类

例子

以下可视为可生产消耗资源：

  • 一个游戏中的木材和矿物
  • 加密货币BTC和ETH，DeFi领域中的ERC20代币
  • 各种法定货币，如美元
  • 系统动力学中存量Stock

可重复使用资源​

不可被生产、不可交换、总数固定、可共享的同质要素，一旦被占用就需要释放后才能再次使用，支持多种类

例子

以下可视为可重复使用资源：

  • 停车场的车位
  • 编程中的进程锁
  • 银行的服务窗口
  • 区块链一个区块的存储容量限制

总之，资源是抽象的同质品，在模型中不存在具体的对象，只有种类及其数量概念

理解资源容器​

  • 以键值对形式分类存储各种资源，键为资源种类名称，值为资源数量，在容器操作时也是按资源种类分门别类的进行
  • 本质是一种特殊的Dict对象，资源容器的键只能为String，值只能为Number格式
  • 定义一个资源容器可以指定有哪些资源种类（容器的键）、每种资源的初始数量（容器对应键的值）、每种资源容量上限、各种资源能否为负值，这些设置将影响到资源操作的效果
提示

在DeFi领域中建模，我们通常将用户钱包、DEX流动性池等视作资源容器，同时将代币名称作为容器的键，将代币数量作为对应的数量，由于容器内各种资源分类存放的工作机制，这样就能轻松管理EOA账户地址和智能合约地址的各种代币余额。

理解资源容器的操作​

提示

“取”和“放”资源的容器操作：

  • 对可生产消耗类资源来说，取出资源可以具体理解为“出库/消费/支付/流出”，与之相对的，放入资源可以理解为“入库/生产/收入/流入”，这取决于你对容器的建模定义。
  • 对可重复使用类资源来说，取出资源可以具体理解为“申请占用”，放入资源理解为“释放占用”。

详见容器操作组件章节。

设置方法​

Containers_image2.png

  • 设置包括三方面：类型选择、机制设置和初始赋值
  • 根据容器所处位置，作为全局容器、实体属性、和局部容器时设置方法不尽相同，详见下

作为全局容器（通用设置）​

类型暂时不可选择，只支持资源容器

批量构造容器键​

新增表达式行​

  • 点击添加按钮，出现一行表达式输入框

  • 最终结果是所有行的表达式构造的结果集合

    Containers_image3.png

输入构造表达式​

使用“构造表达式”在形式上定义容器可能的键

提示

区别于通用表达式可以适用所有表达式输入栏，这些构造表达式用法不是通用语法，如"->"操作符和ProductJoin函数，仅仅用于批量构造键的场合。

Containers_image4.png

构造表达式请关注输入栏智能提示如上图，基本用法如下：

  • 列举：直接输入多个String值作为容器键，并以","隔开即可

  • 指定范围：使用"->"连接两个Number值或String字母值，两者之间所有值都将作为容器键

  • 输入一个[String]，每个元素均作为容器键

  • 直接使用标签集，每个标签均作为容器键

  • 使用笛卡尔积函数ProductJoin对多个List的元素间按顺序排列连接为新String，每个值都将作为容器键，如下图，用法详见技术说明

    Containers_image5.png

构造后预览​

可以点击预览按钮观察效果如上图

构造后效果​

在其它相关设定处会出现相关提示以便于建模，如操作链的资源种类选择，如下图所示

批量构造键案例

在Web3领域中建模时我们可能需要一个钱包，希望它能够存储各种ERC20代币，包括协议代币和两两配对的LP代币（如"WETH-USDC"），如果逐一设置那将非常繁琐，使用批量构造键就非常简单。

  • 假设你有一个名为ERC20的标签集如下左图，你希望容器能够作为钱包支持存储各类ERC20代币余额，那么你可以用批量构造键表达式实现两两配对的LP代币的构造，如下中图，点击预览显示构造的键如右图。
  • 其中有些你可能用不上，如"COMP-COMP"，没关系因为不影响模拟。

  • 请注意：批量构造容器键并非意味着系统在开始运行时会全部初始化所有键值对，你可以理解这是仅仅在形式上预定了规则、方便建模而已，比如下图你可以在方便的为操作链选择资源类型，不会影响运行逻辑。

    Containers_image10+1.png

    系统在以下情况下才会真正的实例化键值对：

    • 在容器的初始化明细配置中指定了资源初始量
    • 在实体Agent个体属性个性化配置中进行了资源初始量设置
    • 建模中使用公式对指定容器的指定资源键赋值数量或进行读取
    • 建模中进行容器操作，对指定资源取放

容量限制​

Containers_image11.png

  • 表示容器内各种资源的默认存储上限
  • 勾选后容器无容量上限
  • 不勾选时下方输入框亮起，输入任意返回非负Number格式的表达式，如果为负值则表示无限

存量可否为负​

Containers_image12.png

勾选可为负，表示容器中各资源数量允许为负值；不勾选表示不能为负

提示：如何理解资源存量可为负?
  • 永远不会出现取出不足的情况
  • 通常用于建模时不关心某种资源的总量，只需要考虑余额变化量的场合 例如DeFi领域中建模，你有一个交易者Agent以$USDC本位低买高卖获利，他有一个资源容器作为钱包，你只关心模拟结束时他的盈利情况，其实你无需给他一个很大的初始$USDC金额作为本金，在最后统计终值后考察与初值的差来衡量收益，而是将钱包$USDC初始量设置为0、容器设置为可为负，则最终盈亏就是余额——如果亏损最终为负，如果盈利为正
  • 系统动力学建模中存量（资源容器）可以设置可为负
模型案例

数量可为负的资源容器Resource中a资源初始值为10，每个Tick取出1，共20Tick，最终剩余a资源-10

提示

容器容量限制和可否为负的设置只有被操作时才有效，公式赋值无效。

公式可以直接修改容器内的资源数量，如 Container.a = 100，即便该资源容量限制为50，也能修改成功，只有被放入操作时才会检查限制条件，比如系统将在下次放入10单位资源时会报错超出容器容量限制。同理，对一个资源不可为负的容器，公式可以成功赋值资源为负值，只有在取出操作时才会提示报错。

默认初始数量​

Containers_image13.png

  • 输入框：接受返回Number的表达式，如果设置了可为负，你也可以输入一个负值
  • 请注意：这里设置的是默认值，如果你在前面批量构造了资源键，那么每种资源默认该初值

初始化明细配置​

Containers_image14.png

  • 明细配置会覆盖上述统一设置的默认值。

  • 点击明细配置按钮如上图，弹出配置界面如下图，从左至右的操作依次为：

    Containers_image15.png

    • 选择资源种类（容器键）
    • 勾选设置是否容量无限，若不勾选则指定该资源的上限
    • 输入资源初始数量表达式
    • 设置能否为负

作为实体属性​

Containers_image16.png

  • 当容器被放置在实体内（流程外）画布时是实体属性

  • 容器机制设置和初始赋值与上述全局容器完全相同，不再赘述，这里设置指的是所有个体默认值

  • 选择归属主体（如上图）：个体 / 观察者

    Containers_image16+1.png

  • 当容器归属为个体时，支持个性化配置每个个体的资源初始化赋值

    Containers_image16+2.png

    • 不做设置时如上图显示“默认”，即所有个体值默认为统一的初始设置值

    • 如需针对个体个性配置初始值，点击上图按钮，在弹窗中的列表中逐一进行如下图

      Containers_image16+3.png

    • 在这里设置，与在所属实体的属性面板的个体个性配置弹窗配置，效果完全一致，但后者一定要打开个体配置，并勾选了该容器并指定了需要的资源key，这里才能操作，如下图

      Containers_image16+4.png

作为流程局部容器时​

  • 容器机制设置和初始赋值与全局容器完全相同，不再赘述
  • 类型选择：容器接口 / 常规容器

容器接口​

Containers_image17.png

  • 寿命基于被触发流程外Trigger，无寄存机制

  • 设置流程资源接口后，本流程轮廓外、流程的调用和请求调用都会出现对应端口，端口符号为"R"

  • 与变量不同，容器只能传递对象，即只能以状态链连接端口的方式传入容器对象，而不能在端口所在对象属性面板上使用容器名称表达式作为参数传入

    Containers_image18.png

常规容器​

类似全局变量或实体属性容器，寿命永久，无寄存机制，设置方法相同

案例​

案例：系统动力学存量转移

Flow流程每个Tick从Stock1容器中转移1个WETH给Stock2容器