GGanalysis

https://onebst.github.io/GGanalysis/
Admin
GGanalysis is a Python package for calculating gacha game probabilities, modeling pull mechanics,...
Tokens:17,780
Snippets:143
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manually Install GGanalysis from GitHub

Source: https://onebst.github.io/GGanalysis/start_using/environment_installation.html

Clone the repository and install locally. Use the -e flag for an editable installation if you intend to modify the source code.

```bash
git clone https://github.com/OneBST/GGanalysis.git
cd GGanalysis
# 如果不需要编辑工具包内代码，直接执行以下命令，安装完成后 git 下载文件可删除
pip install .
# 如果需要编辑工具包内代码，加入 -e 选项，运行时直接引用当前位置的包，对代码的修改会实时反应
pip install -e .
```

--------------------------------

### Install GGanalysis via PyPI

Source: https://onebst.github.io/GGanalysis/start_using/environment_installation.html

Use this command to install the latest stable version of the toolkit from PyPI.

```bash
pip install GGanalysis
```

--------------------------------

### Get a specific 6-star operator in a directional banner

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

Uses PityBernoulliModel to model a banner with a 1/3 probability for a specific target.

```python
import GGanalysis as gg
import GGanalysis.games.arknights as AK
# 六星100%概率，UP三个，故抽到目标UP六星的概率为1/3
triple_up_specific_6star = gg.PityBernoulliModel(AK.PITY_6STAR, 1 / 3) # 尚未证实定向寻访是否存在类型硬保底机制，仅使用保底伯努利模型
dist = triple_up_specific_6star(2) # 在定向寻访池期望抽到目标六星干员两次，此前没有垫抽
print('期望抽数为：{}'.format(dist.exp)) # 期望抽数为：207.56732961125866
```

--------------------------------

### Get non-UP 6-star operators with increased weight in a dual-UP limited banner

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

Calculates the distribution for obtaining non-UP operators that have a specific weight boost.

```python
import GGanalysis as gg
others = 71 # 假设除了主要UP干员和权值提升的非UP六星干员外，其他准许获取的六星干员的数量为71
triple_second_up_specific_6star = gg.PityBernoulliModel(AK.PITY_6STAR, 0.3 / (5 * 3 + others) * 5) # 在当前卡池内，权值提升的非UP六星干员数量一般为3
success_count = 3 # 期望抽到某个权值提升的非UP六星干员三次
dist = triple_second_up_specific_6star(success_count, True) # `multi_dist` 为True表示以列表形式返回分布
for i in range(1, success_count + 1):
    print(f"抽到第{i}个目标干员~期望抽数：{round(dist[i].exp, 2)}，方差：{round(dist[i].var, 2)}") # 结果保留两位小数
```

--------------------------------

### 计算单UP六星干员期望

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

使用 single_up_6star 计算在 4.6 寻访机制更新后的单UP六星期望抽数。

```python
import GGanalysis.games.arknights as AK
dist = AK.single_up_6star(item_num=1, item_pity=0, type_pity=0)
print('4.6寻访机制更新后，无水位时抽到单up六星的期望抽数为：{}'.format(dist.exp))
```

```text
4.6寻访机制更新后，无水位时抽到单up六星的期望抽数为：66.16056206529494
```

--------------------------------

### 计算抽卡计划达成概率 (Python)

Source: https://onebst.github.io/GGanalysis/start_using/check_gacha_plan.html

使用 FiniteDist 类在多个阶段的抽数限制下计算达成目标的概率及期望消耗。此方法适用于每次获得道具独立同分布的抽卡场景。

```python
from GGanalysis import FiniteDist
import GGanalysis.games.zenless_zone_zero as ZZZ
# 设定要抽的角色数量/武器数量以及阶段预算
tasks = [
    [1, 1, 200],
    [1, 0, 74],
    [1, 1, 40],
]
total_c = 0
total_w = 0
total_pulls = 0
ans_dist = FiniteDist([1])
for (num_c, num_w, task_pulls) in tasks:
    total_c += num_c
    total_w += num_w
    total_pulls += task_pulls
    ans_dist *= ZZZ.up_5star_character(num_c) * ZZZ.up_5star_weapon(num_w)
    ans_dist = FiniteDist(ans_dist[:total_pulls+1])
print("成功概率", sum(ans_dist.dist))
ans_dist = ans_dist.normalized()  # 归一化
print("成功玩家期望抽数消耗", ans_dist.exp)
full_dist = ZZZ.up_5star_character(total_c)*ZZZ.up_5star_weapon(total_w)
print("获得计划道具期望", full_dist.exp)
```

--------------------------------

### 通过组合抽卡层自定义抽卡模型

Source: https://onebst.github.io/GGanalysis/start_using/custom_gacha_model.html

通过继承 CommonGachaModel 并手动添加 PityLayer 和 BernoulliLayer 来实现高度定制化的抽卡逻辑。

```python
import GGanalysis as gg
# 定义一个星级带软保底，每个星级内有5种物品，想要获得其中特定一种的模型
# 定义软保底概率上升表，第1-3抽概率0.1，第4抽概率0.6，第5抽保底
pity_p = [0, 0.1, 0.1, 0.1, 0.6, 1]

# 保底伯努利抽卡类
class MyModel(gg.CommonGachaModel):
    # 限制期望的误差比例为 1e-8，达不到精度时分布截断位置为 1e5
    def __init__(self, pity_p, p, e_error = 1e-8, max_dist_len=1e5) -> None:
        super().__init__()
        # 增加保底抽卡层
        self.layers.append(gg.PityLayer(pity_p))
        # 增加伯努利抽卡层
        self.layers.append(gg.BernoulliLayer(p, e_error, max_dist_len))
# 根据自定义的类计算从零开始获取一个道具的分布，由于可能永远获得不了道具，分布是截断的
gacha_model = MyModel(pity_p, 1/5)
# 关于 item_pity 等条件输入，如有需要可以参考预置类中 __call__ 和 _build_parameter_list 的写法
dist = gacha_model(item_num=1)
```

--------------------------------

### 执行分布数量加

Source: https://onebst.github.io/GGanalysis/start_using/basic_concepts.html

将两个分布数组按 0 位置对齐相加，注意结果可能不满足归一性。

```python
dist_c = dist_a + dist_b
print('数量加的分布数组', dist_c.dist)  # [0, 1.5, 0.5]
```

--------------------------------

### 构造马尔可夫转移矩阵

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

使用状态映射字典和邻接表列表构造转移矩阵。

```python
# Epitomized Path & Fate Points
state_num = {'get':0, 'fate1UP':1, 'fate1':2, 'fate2':3}
state_trans = [
    ['get', 'get', 0.375],
    ['get', 'fate1UP', 0.375],
    ['get', 'fate1', 0.25],
    ['fate1UP', 'get', 0.375],
    ['fate1UP', 'fate2', 1-0.375],
    ['fate1', 'get', 0.5],
    ['fate1', 'fate2', 0.5],
    ['fate2', 'get', 1]
]
matrix = table2matrix(state_num, state_trans)
```

--------------------------------

### Model with type hard pity mechanism

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

Demonstrates how to integrate AKHardPityModel into a base model to account for type-based hard pity.

```python
# 添加定向选调前已知存在类型硬保底的卡池为标准寻访中的单UP和双UP池，其它卡池暂无证据表明存在此机制，此处仅为演示如何定义此类模型，不能当做机制参考
import GGanalysis as gg
import GGanalysis.games.arknights as AK
# 假设定向寻访池存在类型硬保底机制

# 六星100%概率，UP三个，故抽到目标UP六星的概率为1/3
triple_up_specific_6star_without_hard_pity = gg.PityBernoulliModel(AK.PITY_6STAR, 1 / 3) # 没有硬保底
triple_up_specific_6star_has_hard_pity = AK.AKHardPityModel(triple_up_specific_6star_without_hard_pity(1), AK.p2dist(AK.PITY_6STAR), type_pity_gap=200, item_types=3, up_rate=1, type_pull_shift=1) # 载入硬保底
dist = triple_up_specific_6star_has_hard_pity(2) # 在定向寻访池期望抽到目标六星干员两次，此前没有垫抽
print('期望抽数为：{}'.format(dist.exp)) # 期望抽数为：207.0218117279958
```

--------------------------------

### 执行分布数量乘

Source: https://onebst.github.io/GGanalysis/start_using/basic_concepts.html

对分布数组进行标量乘法，注意结果可能不满足归一性。

```python
dist_c = dist_a * 2
print('数量乘后的分布数组', dist_c.dist)  # [0. 1. 1.]
```

--------------------------------

### 计算绝区零角色池抽卡分布

Source: https://onebst.github.io/GGanalysis/games/zenless_zone_zero/index.html

使用 GGanalysis 计算在特定垫抽水位和大保底状态下，获取指定数量 UP 角色所需的抽数分布。

```python
import GGanalysis.games.zenless_zone_zero as SR
# 绝区零角色池的计算
print('角色池在垫了20抽，有大保底的情况下抽3个UPS级抽数的分布')
dist_c = SR.up_5star_character(item_num=3, item_pity=20, up_pity=1)
print('期望为', dist_c.exp, '方差为', dist_c.var, '分布为', dist_c.dist)
```

--------------------------------

### FiniteDist Methods

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

Methods available on FiniteDist instances for distribution analysis and transformation.

```APIDOC
## FiniteDist Methods

### calc_cdf()
Converts the current distribution to a Cumulative Distribution Function (CDF).

### calc_dist_attribution(p_error=1e-06)
Calculates basic attributes: `exp`, `var`, and `p_sum`.

### calc_entropy_attribution(p_error=1e-06)
Calculates entropy-related attributes: `entropy_rate` and `randomness_rate`.

### normalized() -> FiniteDist
Returns a normalized version of the distribution.

### quantile_point(quantile_p)
Returns the position of the specified quantile.
```

--------------------------------

### 计算轮换池特定六星获取概率

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

使用 dual_up_specific_6star 计算在轮换池中获取特定六星干员的概率。

```python
import GGanalysis.games.arknights as AK
dist = AK.dual_up_specific_6star(item_num=1)
print('准备100抽，从轮换池捞出玛恩纳的概率只有：{}%'.format(sum(dist[:100+1]) * 100))
```

```text
准备100抽，从轮换池捞出玛恩纳的概率只有：49.60442859476116%
```

--------------------------------

### 计算独立同分布随机变量之和

Source: https://onebst.github.io/GGanalysis/start_using/basic_concepts.html

使用乘方运算计算多个独立同分布随机变量的卷积分布。

```python
dist_c = dist_b ** 3
print('乘方后的分布', dist_c.dist)  # [0. 0. 0. 1.]
```

--------------------------------

### 计算随机变量之和

Source: https://onebst.github.io/GGanalysis/start_using/basic_concepts.html

通过卷积运算计算两个独立随机变量之和的分布。

```python
dist_c = dist_a * dist_b
print('混合后的分布', dist_c.dist)  # [0.  0.  0.5 0.5]
```

--------------------------------

### 使用预定义模板自定义抽卡模型

Source: https://onebst.github.io/GGanalysis/start_using/custom_gacha_model.html

通过 PityBernoulliModel 快速构建包含软保底机制和伯努利分布的抽卡模型。

```python
import GGanalysis as gg
# 定义一个星级带软保底，每个星级内有5种物品，想要获得其中特定一种的模型
# 定义软保底概率上升表，第1-3抽概率0.1，第4抽概率0.6，第5抽保底
pity_p = [0, 0.1, 0.1, 0.1, 0.6, 1]

# 采用预定义的保底伯努利抽卡类
gacha_model = gg.PityBernoulliModel(pity_p, 1/5)
# 根据定义的类计算从零开始获取一个道具的分布，由于可能永远获得不了道具，分布是截断的
dist = gacha_model(item_num=1, item_pity=0)
```

--------------------------------

### 使用转移矩阵计算复合类型保底概率

Source: https://onebst.github.io/GGanalysis/start_using/stationary_distribution.html

通过PriorityPitySystem计算明日方舟中多星级物品耦合后的综合概率。

```python
# 以明日方舟为例，计算明日方舟六星、五星、四星、三星物品耦合后，各类物品的综合概率
import GGanalysis as gg
import GGanalysis.games.arknights as AK
# 按优先级将道具概率表组成列表
item_p_list = [AK.PITY_6STAR, AK.PITY_5STAR, [0, 0.5], [0, 0.4]]
AK_probe = gg.PriorityPitySystem(item_p_list, extra_state=1, remove_pity=True)
# 打印结果，转移矩阵的计算可能比较慢
print(AK_probe.get_stationary_p())  # [0.02890628 0.08948246 0.49993432 0.38167693]
```

--------------------------------

### 创建 FiniteDist 对象

Source: https://onebst.github.io/GGanalysis/start_using/basic_concepts.html

使用列表、numpy 数组或现有 FiniteDist 对象初始化离散分布。

```python
import GGanalysis as gg
import numpy as np

dist_a = gg.FiniteDist([0, 0.5, 0.5])
dist_b = gg.FiniteDist(np.array([0, 1]))
dist_c = gg.FiniteDist(dist_a)
```

--------------------------------

### AK.dual_up_specific_6star

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

计算轮换池获取特定六星干员的抽卡分布（包含类型硬保底）。

```APIDOC
## dual_up_specific_6star(item_num, item_pity=0, type_pity=0, multi_dist=False)

### Description
针对通过统计发现的类型保底机制，计算标准寻访-双UP轮换池中获取特定六星干员的概率。

### Parameters
- **item_num** (int) - Required - 需求道具个数
- **item_pity** (int) - Optional - 道具保底状态，默认为0
- **type_pity** (int) - Optional - 类型保底状态，默认为0

### Request Example
```python
import GGanalysis.games.arknights as AK
dist = AK.dual_up_specific_6star(item_num=1)
print('准备100抽，从轮换池捞出玛恩纳的概率只有：{}%'.format(sum(dist[:100+1]) * 100))
```
```

--------------------------------

### 使用预定义模型计算抽卡分布

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

通过指定初始道具和目标道具状态，获取抽卡次数的 FiniteDist 分布。

```python
import GGanalysis.games.azur_lane as AL
# 碧蓝航线2金3紫卡池在已有1金0紫的情况下集齐剩余1金及特定2紫的情况
dist = AL.model_0_2_3(init_item=['SSR1'], target_item=['SSR1', 'SSR2', 'SR1', 'SR2'])
print('期望为', dist.exp, '方差为', dist.var, '分布为', dist.dist)
```

--------------------------------

### AK.single_up_6star

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

计算标准寻访-单UP六星干员的抽卡分布（包含定向选调机制）。

```APIDOC
## single_up_6star(item_num, item_pity=0, type_pity=0, multi_dist=False)

### Description
针对4.6寻访规则更新后的定向选调机制（类型保底）计算单UP六星干员的概率。

### Parameters
- **item_num** (int) - Required - 需求道具个数
- **item_pity** (int) - Optional - 道具保底状态，默认为0
- **type_pity** (int) - Optional - 定向选调的类型保底状态，默认为0
- **multi_dist** (bool) - Optional - 是否以列表返回分布，默认为False

### Request Example
```python
import GGanalysis.games.arknights as AK
dist = AK.single_up_6star(item_num=1, item_pity=0, type_pity=0)
print('4.6寻访机制更新后，无水位时抽到单up六星的期望抽数为：{}'.format(dist.exp))
```
```

--------------------------------

### AK.limited_up_6star

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

计算双UP限定池获取特定六星干员的抽卡分布。

```APIDOC
## limited_up_6star(item_num, item_pity=0, multi_dist=False)

### Description
计算双UP限定池中获取特定六星干员的概率，不考虑300抽井机制。

### Parameters
- **item_num** (int) - Required - 需求道具个数
- **item_pity** (int) - Optional - 道具保底状态，默认为0

### Request Example
```python
import GGanalysis.games.arknights as AK
dist = AK.limited_up_6star(item_num=5)
print('一井满潜限定的概率：{}%'.format(sum(dist[:300+1]) * 100))
```
```

--------------------------------

### Collect three UP 6-star operators in a joint operation banner

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

Uses AK_Limit_Model to calculate the distribution for collecting multiple specific items in a banner.

```python
import GGanalysis.games.arknights as AK
triple_up_specific_6star = AK.AK_Limit_Model(AK.PITY_6STAR, 1, total_item_types=3, collect_item=3)
dist = triple_up_specific_6star(item_pity=5) # （默认）期望集齐一轮，此前垫了5抽
print('期望抽数为：{}'.format(dist.exp)) # 期望抽数为：188.63258247595024
print('方差为：{}'.format(dist.var)) # 方差为：10416.175324956945
print('100抽以内达成目标的概率为：{}%'.format(sum(dist[:100+1]) * 100)) # 100抽以内达成目标的概率为：16.390307170816875%
```

--------------------------------

### GGanalysis.markov_method.PriorityPitySystem

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

A class representing a priority-based pity system for gacha items.

```APIDOC
## class GGanalysis.markov_method.PriorityPitySystem(item_p_list, extra_state=1, remove_pity=False)

### Description
Initializes a priority-based pity system where items are sorted by priority.

### Parameters
- **item_p_list** (list) - Required - List of item probabilities.
- **extra_state** (int) - Optional - Additional state count.
- **remove_pity** (bool) - Optional - Whether to remove pity mechanics.
```

--------------------------------

### 计算武器活动祈愿抽卡分布

Source: https://onebst.github.io/GGanalysis/games/genshin_impact/gacha_models.html

使用 up_5star_ep_weapon 模型计算在特定保底和命定值下的武器抽取分布。

```python
import GGanalysis.games.genshin_impact as GI
print('武器池池在垫了30抽，有大保底，命定值为1的情况下抽1个UP五星抽数的分布')
dist_w = GI.up_5star_ep_weapon(item_num=1, item_pity=30, up_pity=1, fate_point=1)
print('期望为', dist_w.exp, '方差为', dist_w.var, '分布为', dist_w.dist)
```

--------------------------------

### 计算限定池集齐两种UP六星概率

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

使用 limited_both_up_6star 计算限定池同时获取限定与陪跑六星的概率。

```python
import GGanalysis.games.arknights as AK
dist = AK.limited_both_up_6star()
print('全六党吃井概率：{}%'.format((1-sum(dist[:300+1])) * 100))
```

```text
全六党吃井概率：7.130522684168872%
```

--------------------------------

### 提取 FiniteDist 分布信息

Source: https://onebst.github.io/GGanalysis/start_using/basic_concepts.html

直接访问分布数组或获取期望和方差等统计属性。

```python
print('dist_a 的分布数组', dist_a.dist)  # [0.  0.5 0.5]
print('dist_a 的期望', dist_a.exp)  # 1.5
print('dist_a 的方差', dist_a.var)  # 0.25
```

--------------------------------

### class FiniteDist

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

Initializes a finite 1D discrete distribution. The class supports arithmetic operations such as convolution (*) and distribution addition (+).

```APIDOC
## class FiniteDist(dist: list | ndarray | FiniteDist = [1])

### Description
Represents a finite 1D discrete distribution. It encapsulates a numpy array and provides methods for efficient distribution calculations.

### Parameters
- **dist** (list | ndarray | FiniteDist) - Optional - The initial distribution array. Defaults to [1].

### Attributes
- **dist** (ndarray) - The distribution at natural number positions.
- **exp** (float) - The expectation of the distribution.
- **var** (float) - The variance of the distribution.
- **p_sum** (float) - The sum of probabilities.
- **entropy_rate** (float) - The entropy rate of the distribution.
- **randomness_rate** (float) - The randomness rate compared to a Bernoulli source.

### Usage Example
```python
dist_a = FiniteDist([0.5, 0.5])
dist_b = FiniteDist([0, 1])
# Convolution
result = dist_a * dist_b
# Self-convolution
result_pow = dist_b ** 10
```
```

--------------------------------

### 处理 200 抽天井机制

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

通过合并未触发天井和触发天井后的累积概率密度函数 (CDF) 来处理 200 抽天井情况。

```python
import GGanalysis as gg
import GGanalysis.games.azur_lane as AL
# 对于 1_1_3 带200天井的情况，需要单独处理
dist_0 = AL.model_1_1_3(target_item=['UR1', 'SSR1'])  # 未触发200天井时
dist_1 = AL.model_1_1_3(target_item=['SSR1'])  # 触发200天井时
cdf_0 = gg.dist2cdf(dist_0)
cdf_1 = gg.dist2cdf(dist_1)
cdf_0 = cdf_0[:min(len(cdf_0), len(cdf_1))]
cdf_1 = cdf_1[:min(len(cdf_0), len(cdf_1))]
cdf_0[200:] = cdf_1[200:]
# 此时 cdf_0 就是含天井的累积概率密度函数
```

--------------------------------

### 计算角色活动祈愿抽卡分布

Source: https://onebst.github.io/GGanalysis/games/genshin_impact/gacha_models.html

使用 up_5star_character 模型计算在特定保底状态下获取多个 UP 五星角色的抽数分布。

```python
import GGanalysis.games.genshin_impact as GI
# 原神角色池的计算
print('角色池在垫了20抽，有大保底，已经连歪两次的情况下抽3个UP五星抽数的分布')
dist_c = GI.up_5star_character(item_num=3, item_pity=20, up_pity=1, cr_pity=2)
print('期望为', dist_c.exp, '方差为', dist_c.var, '分布为', dist_c.dist)
```

--------------------------------

### 计算角色活动跃迁抽卡分布

Source: https://onebst.github.io/GGanalysis/games/honkai_star_rail/gacha_models.html

使用 up_5star_character 函数计算在特定垫抽和保底状态下获取多个 UP 五星角色的抽数分布。

```python
import GGanalysis.games.honkai_star_rail as SR
# 崩坏：星穹铁道角色池的计算
print('角色池在垫了20抽，有大保底的情况下抽3个UP五星抽数的分布')
dist_c = SR.up_5star_character(item_num=3, item_pity=20, up_pity=1)
print('期望为', dist_c.exp, '方差为', dist_c.var, '分布为', dist_c.dist)
```

--------------------------------

### 使用迭代方法计算n连抽获得k个道具概率

Source: https://onebst.github.io/GGanalysis/start_using/stationary_distribution.html

利用multi_item_rarity计算平稳状态下进行n连抽获得特定数量道具的分布。

```python
# 以原神10连获得多个五星道具为例
import GGanalysis as gg
import GGanalysis.games.genshin_impact as GI
# 获得平稳后进行10连抽获得k个五星道具的分布
ans = gg.multi_item_rarity(GI.PITY_5STAR, 10)
```

--------------------------------

### 计算获取任意六星干员的期望

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

使用 common_6star 方法计算获取任意六星干员的期望抽数。

```python
import GGanalysis.games.arknights as AK
dist = AK.common_6star(item_num=1)
print('抽到六星的期望抽数为：{}'.format(dist.exp))  # 34.59455493520977
```

--------------------------------

### 使用明日方舟预定义模型计算抽卡分布

Source: https://onebst.github.io/GGanalysis/start_using/use_predefined_model.html

通过导入 arknights 模块并调用 dual_up_specific_6star 函数计算普池双UP抽卡分布。

```python
# 计算抽卡所需抽数分布律 以明日方舟为例
import GGanalysis.games.arknights as AK
# 普池双UP的计算 item_num是要抽多少个 item_pity是当前垫了多少抽，从零开始填0就行
dist_c = AK.dual_up_specific_6star(item_num=3, item_pity=20)
print('期望为', dist_c.exp, '方差为', dist_c.var, '分布为', dist_c.dist)
```

--------------------------------

### GeneralCouponCollection Class

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

A class for solving coupon collection problems where probabilities are unequal. It treats the collection state as an absorbing state.

```APIDOC
## GeneralCouponCollection

### Description
Initializes a collector for items with unequal probabilities.

### Constructor
`GeneralCouponCollection(p_list: list | ndarray, item_names: list[str] = None)`

### Methods
- **collection_dp(n, init_state=None)**: Calculates state distribution after n draws using DP.
- **decode_state_number(state_num)**: Returns the list of items corresponding to a state number.
- **encode_state_number(item_list)**: Generates a state number from a list of items.
- **get_collection_p(n, init_state=None, target_state=None, DP_array=None)**: Returns the probability array of reaching the target state after n draws.
- **get_expectation(state=None, target_state=None)**: Calculates the expected number of draws to reach the target state using cached recursion.
- **get_satisfying_state(target_state=None)**: Returns a 01 numpy array marking states that satisfy the target requirements.
- **sim_collection(state=None)**: Performs a Monte Carlo simulation of draw counts for verification.
```

--------------------------------

### FiniteDist 随机变量分布运算示例

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

展示如何定义随机变量并进行卷积运算以及累加计算。

```python
# 定义随机变量 dist_a
dist_a = FiniteDist([0.5, 0.5])
# 定义随机变量 dist_b
dist_b = FiniteDist([0, 1])
# 通过卷积计算两个随机变量叠加 dist_a + dist_b 的分布
dist_a * dist_b
# 计算独立同分布的随机变量 dist_b 累加 10 次后的分布
dist_b ** 10
```

--------------------------------

### gacha_model.model_1_1_3

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

Calculates the pull distribution for a pool with 1 UR, 1 SSR, and 3 SR items.

```APIDOC
## gacha_model.model_1_1_3(target_item: list = None) -> FiniteDist

### Description
Calculates the pull distribution for a pool with 1 UR, 1 SSR, and 3 SR items. Returns a FiniteDist object representing the required number of pulls.

### Parameters
- **target_item** (list) - Optional - A list of strings representing the target items to collect.
```

--------------------------------

### 计算限定池获取特定六星概率

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

使用 limited_up_6star 计算限定池中获取特定六星干员的概率，注意此模型不包含井的后处理。

```python
import GGanalysis.games.arknights as AK
dist = AK.limited_up_6star(item_num=5)
print('一井满潜限定的概率：{}%'.format(sum(dist_4[:300+1]) * 100))
```

```text
一井满潜限定的概率：14.881994954229667%
```

--------------------------------

### AK.limited_both_up_6star

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

计算双UP限定池集齐两种UP六星干员的抽卡分布。

```APIDOC
## limited_both_up_6star(item_pity=0)

### Description
计算限定池同时获取限定6星及陪跑6星的模型。

### Parameters
- **item_pity** (int) - Optional - 道具保底状态，默认为0

### Request Example
```python
import GGanalysis.games.arknights as AK
dist = AK.limited_both_up_6star()
print('全六党吃井概率：{}%'.format((1-sum(dist[:300+1])) * 100))
```
```

--------------------------------

### Collect two UP 5-star operators in a standard rotation banner

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

Uses AK_Limit_Model to calculate the expected pulls to collect two specific 5-star operators.

```python
import GGanalysis.games.arknights as AK
both_up_5star = AK.AK_Limit_Model(AK.PITY_5STAR, 0.5, total_item_types=2, collect_item=2)
dist = both_up_5star()  # 期望在轮换单UP池中抽到两个UP的五星干员，此前没有垫抽
print('期望抽数为：{}'.format(dist.exp))  # 期望抽数为：63.03402819816313
```

--------------------------------

### coupon_collection.get_equal_coupon_collection_exp

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

Calculates the expected number of draws to collect all items when probabilities are equal.

```APIDOC
## coupon_collection.get_equal_coupon_collection_exp(init_type=0, target_type=None)

### Description
Computes the expected number of draws required to collect all items assuming equal probability for each item.
```

--------------------------------

### gacha_model.model_0_1_1

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

Calculates the pull distribution for a pool with 0 UR, 1 SSR, and 1 SR item.

```APIDOC
## gacha_model.model_0_1_1(target_item: list = None) -> FiniteDist

### Description
Calculates the pull distribution for a pool with 0 UR, 1 SSR, and 1 SR item. Returns a FiniteDist object representing the required number of pulls.

### Parameters
- **target_item** (list) - Optional - A list of strings representing the target items to collect.
```

--------------------------------

### gacha_model.model_0_2_3

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

Calculates the pull distribution for a pool with 0 UR, 2 SSR, and 3 SR items.

```APIDOC
## gacha_model.model_0_2_3(target_item: list = None) -> FiniteDist

### Description
Calculates the pull distribution for a pool with 0 UR, 2 SSR, and 3 SR items. Returns a FiniteDist object representing the required number of pulls.

### Parameters
- **target_item** (list) - Optional - A list of strings representing the target items to collect.
```

--------------------------------

### gacha_model.model_0_3_2

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

Calculates the pull distribution for a pool with 0 UR, 3 SSR, and 2 SR items.

```APIDOC
## gacha_model.model_0_3_2(target_item: list = None) -> FiniteDist

### Description
Calculates the pull distribution for a pool with 0 UR, 3 SSR, and 2 SR items. Returns a FiniteDist object representing the required number of pulls.

### Parameters
- **target_item** (list) - Optional - A list of strings representing the target items to collect.
```

--------------------------------

### gacha_model.dual_up_specific_5star

Source: https://onebst.github.io/GGanalysis/games/arknights/index.html

Calculates the probability distribution for obtaining a specific 5-star operator in a dual-UP banner.

```APIDOC
## gacha_model.dual_up_specific_5star(_calc_pull : int = None_) -> FiniteDist

### Description
Retrieves the probability distribution for obtaining a specific 5-star operator in a dual-UP banner.

### Parameters
- **_calc_pull** (int) - Optional - The number of pulls already performed.
```

--------------------------------

### 绘制原神抽卡概率分布图

Source: https://onebst.github.io/GGanalysis/start_using/quick_visualization.html

通过组合不同物品的分布并使用DrawDistribution模块进行可视化。适用于快速查看抽卡期望与概率分布情况。

```python
import GGanalysis.games.genshin_impact as GI
# 获得原神抽一个UP五星角色+定轨抽特定UP五星武器的分布
dist = GI.up_5star_character(item_num=1) * GI.up_5star_ep_weapon(item_num=1)
# 导入绘图模块
from GGanalysis.gacha_plot import DrawDistribution
fig = DrawDistribution(dist, show_description=True)
fig.show_two_graph(dpi=72)
```

--------------------------------

### gacha_model.model_0_2_2

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

Calculates the pull distribution for a pool with 0 UR, 2 SSR, and 2 SR items.

```APIDOC
## gacha_model.model_0_2_2(target_item: list = None) -> FiniteDist

### Description
Calculates the pull distribution for a pool with 0 UR, 2 SSR, and 2 SR items. Returns a FiniteDist object representing the required number of pulls.

### Parameters
- **target_item** (list) - Optional - A list of strings representing the target items to collect.
```

--------------------------------

### gacha_model.model_0_2_1

Source: https://onebst.github.io/GGanalysis/games/azur_lane/index.html

Calculates the pull distribution for a pool with 0 UR, 2 SSR, and 1 SR item.

```APIDOC
## gacha_model.model_0_2_1(target_item: list = None) -> FiniteDist

### Description
Calculates the pull distribution for a pool with 0 UR, 2 SSR, and 1 SR item. Returns a FiniteDist object representing the required number of pulls.

### Parameters
- **target_item** (list) - Optional - A list of strings representing the target items to collect.
```

--------------------------------

### gacha_model.up_5star_ep_weapon

Source: https://onebst.github.io/GGanalysis/games/genshin_impact/gacha_models.html

Calculates the distribution of pulls required to obtain a specific UP 5-star weapon with the Epitomized Path system.

```APIDOC
## gacha_model.up_5star_ep_weapon

### Description
Calculates the pull distribution for obtaining a specific UP 5-star weapon in the weapon event banner using the Epitomized Path (fate_point) system.

### Parameters
- **item_num** (int) - Required - Number of items to obtain.
- **item_pity** (int) - Optional - Current 5-star pity count.
- **up_pity** (int) - Optional - Current UP guarantee status.
- **fate_point** (int) - Optional - Current fate point count.

### Response
- **FiniteDist | list** - Returns the probability distribution of pulls required.
```

--------------------------------

### gacha_model.up_5star_character

Source: https://onebst.github.io/GGanalysis/games/honkai_star_rail/gacha_models.html

Calculates the probability distribution for obtaining UP 5-star characters in the character event banner, accounting for both item pity and up pity (guaranteed status).

```APIDOC
## gacha_model.up_5star_character

### Description
Calculates the distribution of pulls required to obtain a specified number of UP 5-star characters in the Honkai: Star Rail character event banner.

### Parameters
- **item_num** (int) - Required - Number of items to obtain.
- **multi_dist** (bool) - Optional - Whether to return the distribution list for 1 to item_num items.
- **item_pity** (int) - Optional - Current item pity (pity count).
- **up_pity** (int) - Optional - Current UP pity (1 indicates guaranteed UP character).

### Response
- **FiniteDist | list** - Returns a distribution object or list containing the probability distribution of pulls.
```

--------------------------------

### markov_method.calc_stationary_distribution

Source: https://onebst.github.io/GGanalysis/reference_manual/basic_tools.html

Calculates the stationary distribution for a transition matrix.

```APIDOC
## markov_method.calc_stationary_distribution()

### Description
Calculates the stationary distribution corresponding to the transition matrix, represented as a column vector.
```

--------------------------------

### 联合计算与运气对比

Source: https://onebst.github.io/GGanalysis/games/genshin_impact/gacha_models.html

通过模型乘法计算联合抽卡分布，并利用分布计算玩家抽卡排位百分比。

```python
# 联合角色池和武器池
print('在前述条件下抽3个UP五星角色，1个特定UP武器所需抽数分布')
dist_c_w = dist_c * dist_w
print('期望为', dist_c_w.exp, '方差为', dist_c_w.var, '分布为', dist_c_w.dist)

# 对比玩家运气
dist_c = GI.up_5star_character(item_num=10)
dist_w = GI.up_5star_ep_weapon(item_num=3)
print('在同样抽了10个UP五星角色，3个特定UP五星武器的玩家中，仅花费1000抽的玩家排名前', str(round(100*sum((dist_c * dist_w)[:1001]), 2))+'%')
```
Tokens:
Raw