农业灌溉主体

In progress

该部分文档仍在积极开发中。

主体生成

由于本研究近考虑黄河流域的灌溉农业（使用地表水配额的主要作物生产方式），主体仅在存在灌溉的范围内生成，依赖于 水资源管理主体 方法。

初步博弈意愿

API Reference

农民超过水资源配额的意愿，但意愿并不代表最终决策。

只有两个可能的取值： - D: 如果作物有需要，且经济实惠，则可能会违反最严格水资源配额。 - C: 遵循最严格水资源配额。作物的额外需要会用地下水进行灌溉。

当年份大于等于设置的强制年份时，农民会强制遵守规则。 这一设定对应着一种政策，即在某一年份之后，农民必须遵守水资源配额。 黄河历史上，强制的水资源分配政策在 1999 年开始正式实施。

灌溉用水决策

灌溉水平衡

对某个位于 \(x, y\) 的农民主体 \(v\) 而言，其决策核心是通过取地表水 \(W_{s, v}\) 或地下水 \(W_{g, v}\) 来进行灌溉，使得灌溉水 \(W_{irr, v}\) 在计算运输和田间施用时损失（用灌溉用水效率系数 \(\eta_v\) 表示）后，满足此处作物的净需水 \(D_{x, y}\)， 从而保障农作物生长：

\[ D_{x, y} = W_{irr, v} * \eta_{v} = (W_{g, v} + W_{s, v}) * \eta_{v} \]

根据情景设置的不同，\(W_{irr, v}\) 和 \(\eta_v\) 中有一个是已知的，因此在自然子系统完成对 \(D_{x, y}\) 的估算后，主体 \(v\) 便确定了应该的灌溉量 \(W_{irr}\)。接下来在满足一定边界条件的情况下，农民主体 \(v\) 需要通过社会子系统中得到的收益最大化，从而将灌溉水 \(W_{irr}\) 区分来源为地表水 \(W_{s}\) 和 \(W_g\)。

取水边界条件

除满足 \(W_{s} + W_{g} = W_{irr}\) 条件外，地表取水量 \(W_s\) 还应该满足边界条件：

• 若主体 \(v\) 的初步博弈意愿为违背取水额度 \(Q_v\)，则 \(W_s \in [0, W_{irr}]\)
• 若主体 \(v\) 的初步博弈意愿为遵循取水额度 \(Q_v\)，则 \(W_s \in [0, Q_v]\)

API Reference

决定取用水资源灌溉的下界/上界。

如果该主体意向是选择了遵守制度，那么用水上限就是水资源配额。 如果该主体选择了违背制度，那么上限就是今年所有的灌溉量。

Parameters:

Name	Type	Description	Default
seasonal_irr	float	本年度的灌溉量。	required

Returns:

Type	Description
float	包括用水下界（0.0）和上界的元组。

Source code in src/api/farmer.py

def decide_boundaries(
    self,
    seasonal_irr: float,
) -> float:
    """决定取用水资源灌溉的下界/上界。

    如果该主体意向是选择了遵守制度，那么用水上限就是水资源配额。
    如果该主体选择了违背制度，那么上限就是今年所有的灌溉量。

    Parameters:
        seasonal_irr:
            本年度的灌溉量。

    Returns:
        包括用水下界（0.0）和上界的元组。
    """
    if self.willing == "C":
        ub = min(self.quota, seasonal_irr)
    else:
        ub = seasonal_irr
    return 0.0, ub

灌溉水量调优

确定了取水边界条件之后，主体将使用遗传算法，根据社会子系统中计算得到的收益，对其地表水 \(W_s\) 和 \(W_g\) 取水量进行调优。

API Reference

农民开始触发一次灌溉。 1. 决定这次灌溉的上下界。 2. 利用遗传算法，根据地表/地下用水量不同带来的收益差距，估计用水的来源。 3. 针对最优的地表/地下用水组合，最后计算并记录当年的得分。

Parameters:

Name	Type	Description	Default
seasonal_irr	Optional[float]	本年度的灌溉量。	None
water_prices	Optional[dict]	水资源价格，一个字典，包括地表水和地下水的价格。	None
crop_prices	Optional[dict]	作物价格，一个字典，包括作物的价格。	None

Returns:

Type	Description
Tuple[float, float]	本次灌溉的地表水用量和地下水用量。

Source code in src/api/farmer.py

def irrigating(
    self,
    seasonal_irr: Optional[float] = None,
    water_prices: Optional[dict] = None,
    crop_prices: Optional[dict] = None,
    **kwargs,
) -> Tuple[float, float]:
    """农民开始触发一次灌溉。
    1. 决定这次灌溉的上下界。
    2. 利用遗传算法，根据地表/地下用水量不同带来的收益差距，估计用水的来源。
    3. 针对最优的地表/地下用水组合，最后计算并记录当年的得分。

    Parameters:
        seasonal_irr:
            本年度的灌溉量。
        water_prices:
            水资源价格，一个字典，包括地表水和地下水的价格。
        crop_prices:
            作物价格，一个字典，包括作物的价格。

    Returns:
        本次灌溉的地表水用量和地下水用量。
    """
    if seasonal_irr is None:
        seasonal_irr = self.seasonal_irrigation
    boundaries = self.decide_boundaries(seasonal_irr)
    if boundaries[1] <= 0.0:
        self.surface_water = 0.0
        self.ground_water = 0.0
        return
    crop_yield = {self.crop: self.dry_yield}
    opt_surface, opt_ground = self.water_withdraw(
        ufunc=self.calc_payoff,
        surface_boundaries=boundaries,
        total_irrigation=seasonal_irr,
        water_prices=water_prices,
        crop_yield=crop_yield,
        **kwargs,
    )
    # 用优化过的用水量计算收益，不进行排名，存储结果
    self.calc_payoff(
        crop_yield=crop_yield,
        q_surface=opt_surface,
        q_ground=opt_ground,
        water_prices=water_prices,
        crop_prices=crop_prices,
        rank=False,
        record=True,
    )
    return opt_surface, opt_ground

策略更新

主体间会因收益 \(P\) 不同而学习更优秀的策略 \(S_i\)，因此该决策博弈会随模型时间 \(1, 2, ... t\) 发生演化。

对任意个有联系的主体 \(v_1, v_2, \dots, v_i, v_i \in V\)，每个人在下一时间步 \(t+1\) 的决策 \(S_{1}^{t+1}\) 将受到上一时间步 \(t\) 得分 \(P_1^t, P_2^t\) 较高者的决策 \(S_i^t\) 影响：

\[ S_{v_i}^{t+1} = f(S_{v_j}^{t}), v_i, v_j\in V, E_{v_i} \leq E_{v_j} \]

默认的更新策略 \(f\) 为直接学习最优的策略：

\[S_{v_i}^{t+1} = S_{v_j}^{t}, v_i, v_j \in V, argmax(E_{v_j}) \]

API Reference

由于主体最后的表现不同，主体之间可能存在强化学习行为。

从表现比较好的朋友处学习。

Parameters:

Name	Type	Description	Default
metric	str	评价自己或者同伴表现是否优异的关键指标。 在这个模型中，我们主要有三种潜在的指标： 1. e: 经济得分。即抛除用水成本之后灌溉得到的经济收益。 2. s: 社会得分。即所有农民在评价朋友后得到的社会满意度。 3. payoff: 综合得分。即经济得分和社会得分的乘积。	required
how	str	如果有多个比自己表现优异的其他主体，如何从他们身上学习？ 1. 如果how='best'，仅从表现最好的主体身上学习。 2. 如果how=random，可以从任何一个比自己表现好的个体身上学习。	required

Returns:

Type	Description
bool	这个主体是否进行了属性的变更。

Source code in src/api/farmer.py

def change_mind(self, metric: str, how: str) -> bool:
    """由于主体最后的表现不同，主体之间可能存在强化学习行为。

    从表现比较好的朋友处学习。

    Parameters:
        metric:
            评价自己或者同伴表现是否优异的关键指标。
            在这个模型中，我们主要有三种潜在的指标：
            1. `e`: 经济得分。即抛除用水成本之后灌溉得到的经济收益。
            2. `s`: 社会得分。即所有农民在评价朋友后得到的社会满意度。
            3. `payoff`: 综合得分。即经济得分和社会得分的乘积。
        how:
            如果有多个比自己表现优异的其他主体，如何从他们身上学习？
            1. 如果`how='best'`，仅从表现最好的主体身上学习。
            2. 如果`how=random`，可以从任何一个比自己表现好的个体身上学习。

    Returns:
        这个主体是否进行了属性的变更。
    """
    better_friends = self.friends.better(metric=metric, than=self)
    # 如果没有比自己表现更好的，则直接返回 False
    if not better_friends:
        return False
    elif how == "best":
        friend = better_friends.better(metric=metric).random.choice()
    elif how == "random":
        friend = better_friends.random.choice()
    # 存在比自己表现更好的主体，向他学习。
    self.boldness = friend.boldness
    self.vengefulness = friend.vengefulness
    return True