modules.geoSurvey 模块帮助

本章节包含 modules.geoSurvey 包中常用「工程地质 / 勘察相关计算」模块的使用说明和示例，例如：

地震参数查询与设防参数计算
新近堆积黄土判别（RecentlyDepositedLoess）
黄土湿陷性计算（Collapsibility）
地基液化判别（Liquefaction）
水土腐蚀性评价（WaterSoilCorrosion）等（详见 modules.geoSurvey）

SeismicDesignParameters

模块简介与适用场景

SeismicDesignParameters 根据点位经纬度查询地震动参数，并按 GB 18306 计算设防参数；输出字段见下文「输出字段说明」。
查询经 GDIM 接口完成。除 ``InputToken``（GDIM 登录 token）外，**账号/项目还需在 GDIM 侧配置有效的地震动查询参数接口密钥**（与 GB 18306 地震动参数服务绑定）；密钥缺失或无效时无法返回 epa/tg，详见下文 note。
典型适用场景：
- 在勘察成果/设计输入中，需要快速获取项目区的地震动参数与设防信息；
- 在自动化 pipeline 中，根据钻孔/场地坐标批量补全地震参数字段；
- 作为液化、场地类别等后续分析的输入条件之一。

端口说明

输入端口
- InputPoint：点位信息（ResultModel），至少含经纬度（GeneralProps.Longitude / GeneralProps.Latitude）；亦可通过参数 point 传入。
- InputToken：鉴权 Token；亦可通过参数 token / host 传入，或由 pipeline 统一配置。
输出端口
- OutputResult：地震设计参数结果（ResultModel；见下文「输出字段说明」）

快速上手示例：根据经纬度查询并计算设防参数

from gdisdk.dataclass import Units
from gdisdk.dataclass.results import ResultModel, UnitField
from gdisdk.dataclass.terminologies import GeneralProps
from gdisdk.modules.geoSurvey import SeismicDesignParameters

# 1) 构造点位（经纬度）
point = ResultModel.from_dict(
    {
        GeneralProps.Longitude.value: 104.0668,  # 成都附近示例，经度
        GeneralProps.Latitude.value: 30.5728,  # 成都附近示例，纬度
    },
    model_name="PointLonLat",
    fields_meta={
        GeneralProps.Longitude.value: UnitField(
            title=GeneralProps.Longitude.title, unit=Units.DEGREE
        ),
        GeneralProps.Latitude.value: UnitField(
            title=GeneralProps.Latitude.title, unit=Units.DEGREE
        ),
    },
)

# 2) 直接调用模块（最小可运行）
mod = SeismicDesignParameters(mname="SeismicParams")
mod.InputToken = ("你的GDIM Token", None, None)
mod.InputPoint = point

mod.execute()
result = mod.OutputResult.data

Note

地震动查询参数接口密钥：若 GDIM 未配置或密钥无效，底层接口返回「密匙错误」时，模块会发出 GDIWarning，提示「地震动参数查询没有有效的密钥，无法查询，请检查。」，OutputResult 中 epa/tg 及由它们推导的设防字段均为 None。请在 GDIM 平台为当前 pipeline 使用的登录账号/项目检查并配置该接口密钥。
坐标与坐标系：若 epa/tg 为空且非上述密钥问题，模块会发出 GDIDataQualityWarning：「地震参数查询失败，请检查坐标和坐标系是否正确!」。
点位坐标建议使用 经纬度（WGS84 / EPSG:4326）；若你的点位来自投影坐标，请先做坐标转换再查询。
若 InputPoint 或 InputToken 未提供，模块不发起 HTTP 查询，OutputResult 为 None。

输出字段说明（OutputResult）

OutputResult 为 ResultModel，通常包含以下字段（以 GeoResults 字段名命名，可通过属性或字典式下标访问）：

GeoResults.EffectivePeakAcceleration：有效峰值加速度（epa / (a_{max})）
GeoResults.CharacteristicPeriodOfSeismicAccelerationResponseSpectrum：地震加速度反应谱特征周期（tg / (T_g)）
GeoResults.SeismicDesignIntensity：地震设防烈度
GeoResults.SeismicDesignGroup：地震分组（第一组/第二组/第三组）

参数说明

SeismicDesignParameters 参数一览
参数名	类型	默认值	说明
`point`	`ResultModel \| None`	`None`	点位信息（经纬度）。也可通过输入端口 `InputPoint` 传入。
`token`	`str \| None`	`None`	GDIM 登录 token（Bearer 鉴权，用于调用查询接口）。不包含地震动查询参数接口密钥；后者在 GDIM 平台按账号/项目配置。也可通过 `InputToken` 端口传入。
`host`	`str \| None`	`None`	服务地址；为 `None` 时使用平台默认配置（或由 pipeline 的 host 提供）。
`gdim`	`bool`	`True`	数据平台开关（GDIM/GBIM 兼容用途）。一般保持默认即可。

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.dataclass import Units
from gdisdk.dataclass.results import ResultModel, UnitField
from gdisdk.dataclass.terminologies import GeneralProps
from gdisdk.modules.geoSurvey import SeismicDesignParameters

pipe = PipeLine(app_name="SeismicParamsDemo", app_title="地震参数查询示例")

# 在 Pipeline 上统一配置 GDIM 凭证（模块会优先使用 pipeline 的值）
pipe.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

point = ResultModel.from_dict(
    {
        GeneralProps.Longitude.value: 104.0668,
        GeneralProps.Latitude.value: 30.5728,
    },
    model_name="PointLonLat",
    fields_meta={
        GeneralProps.Longitude.value: UnitField(
            title=GeneralProps.Longitude.title, unit=Units.DEGREE
        ),
        GeneralProps.Latitude.value: UnitField(
            title=GeneralProps.Latitude.title, unit=Units.DEGREE
        ),
    },
)

mod = SeismicDesignParameters("SeismicParams")
mod.InputPoint = point
pipe.add_module(mod)
pipe.run()

result = mod.OutputResult.data

RecentlyDepositedLoess

模块简介与适用场景

RecentlyDepositedLoess 读取 勘察数理统计表**（按地层汇总的常规土工指标），对每层 **平均值 行计算判别指标 R，并与临界值 R₀ = −154.8 比较，判定是否为 新近堆积黄土。
压缩系数取 0～100 kPa 与 50～150 kPa 两段统计中的 较大值；天然密度（g/cm³）在模块内按 ``gravity``（默认 9.8 m/s²）换算为重度 γ（kN/m³，γ = 密度 × gravity）。
典型场景：特殊性岩土章节批量输出新近堆积黄土判别表；pipeline 中接 GdimAppSurveyStatReader 读「常规试验表」等统计结果后直接计算。

端口说明

输入端口
- InputStatTables：TableData 或 TableCollection``（数理统计表）。可通过参数 ``stat_tables 赋值。
输出端口
- OutputTableData：TableData``（``name 为 RecentlyTable，标题「新近堆积黄土判别表」）。输入为空、必需列缺失、行数不一致，或 get_recently_calc_data 校验失败时为 None。

execute() 的返回值与 OutputTableData 一致。

输入表要求

输入须为 按层统计 的长表，且列 field name 包含以下字段（缺任一列时输出 None）：

字段名	说明
`layer_number`	地层编号。也接受已保存结果中的 `layer_num`。
`material_name`	地层名称 / 岩土名称
`statistics_item`	统计项；模块只使用平均值行
`natural_void_ratio`	天然孔隙比 e
`compressibility_coefficient_0_01`	压缩系数（0～100 kPa 段）；与下一字段至少一段有值
`compressibility_coefficient_005_015`	压缩系数（50～150 kPa 段）
`natural_density`	天然密度（g/cm³）
`natural_moisture_content`	天然含水率（%）

数据筛选规则

仅 statistics_item == "平均值" 的行参与计算。
每层须同时有有效的 e、密度、含水率，且两段压缩系数 至少一段非空；否则该层跳过。
InputStatTables 为 TableCollection 时：未设置 stat_table_name 则取集合 第一张表**（``table_titles[0]``）；多表时需指定 ``stat_table_name`` 为表 **name 或 title。

计算规则说明

判别式（与 gdi.geocal.loessCal.recent_depos_loess_justify 一致）：

\[R = -68.45\,e + 10.98\,a - 7.16\,\gamma + 1.18\,\omega\]

其中 \(e\) 为孔隙比，\(a\) 为压缩系数 [MPa⁻¹]，\(\gamma\) 为重度 [kN/m³]，\(\omega\) 为天然含水率 [%]。当 \(R > R_0`（:math:`R_0 = -154.8\)）时判别为 是新近堆积黄土，否则为 非新近堆积黄土。

输出字段说明（OutputTableData）

除输入侧换算后的 e、a、γ、ω 外，还包含：

recentValue：R
recentValueJustify：是 / ``否``（是否满足 \(R > R_0\)）
recentValueJustifyResult：文字结论（是新近堆积黄土 / 非新近堆积黄土）

参数说明

RecentlyDepositedLoess 参数一览
参数名	类型	默认值	说明
`stat_tables`	`TableData \| TableCollection \| None`	`None`	数理统计表；赋值后写入 `InputStatTables`。
`stat_table_name`	`str \| None`	`None`	`TableCollection` 输入时指定目标表 name/title；为 `None` 时用集合第一张表。
`gravity`	`float`	`9.8`	重力加速度（m/s²）。天然密度（g/cm³）换算为重度（kN/m³）：重度 = 密度 × gravity。

快速上手示例：接勘察数理统计读表

from gdisdk.modules.geoSurvey import RecentlyDepositedLoess
from gdisdk.modules.readers import GdimAppSurveyStatReader

reader = GdimAppSurveyStatReader(mname="ReadSurveyStat")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
reader.stat_type = "常规试验表"
reader.column_name = "name"
reader.execute()
stat_tables = reader.OutputTables.data

mod = RecentlyDepositedLoess(mname="RecentLoess")
mod.InputStatTables = stat_tables
mod.execute()

result = mod.OutputTableData.data

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.geoSurvey import RecentlyDepositedLoess
from gdisdk.modules.readers import GdimAppSurveyStatReader

pipe = PipeLine(app_name="RecentLoessDemo", app_title="新近堆积黄土判别示例")

reader = GdimAppSurveyStatReader(mname="ReadSurveyStat")
reader.stat_type = "常规试验表"
reader.column_name = "name"

recent = RecentlyDepositedLoess(mname="RecentLoess")

pipe.add_module(reader)
pipe.add_module(recent)
reader.OutputTables >> recent.InputStatTables
pipe.run()

out = recent.OutputTableData.data

Note

读表模块 column_name 须为 "name"，以保证列名为 layer_number、natural_void_ratio 等与模块一致；若使用 title，请先确认字段名仍能被 TableData.field_names 识别。
输出为单层一行（通过筛选的层）；无有效层时得到 **空表**（仍可能为非 None 的 TableData，行数为 0）。

更多信息

Collapsibility

模块简介与适用场景

Collapsibility 根据钻孔、地层、常规土工试验与黄土湿陷性试验数据，按湿陷性黄土工程地质分区计算 自重湿陷量 与 湿陷量，并给出湿陷类型、湿陷等级及分样明细。
起算面：自重湿陷量从天然地面（孔口标高）起算；湿陷量从基础底面标高起算（详见「计算规则说明」）。
典型场景：勘察成果中批量汇总各孔湿陷性评价指标；在 pipeline 中接 GdimTableReader 读入四张表后一键计算并写回或出报表。

端口说明

输入端口
- InputTables：TableCollection，须同时包含四张表（表 name 见「输入表要求」）。也可在构造后通过模块参数 tables 赋值（等价写入 InputTables）。
输出端口
- OutputTableCollection：TableCollection``（主表 + 2 张子表）。若输入为空、或汇总后任一输出表无数据行，则为 ``None。

execute() 的返回值与 OutputTableCollection 一致。

输入表要求

模块通过 TableCollection.get_table(...) 按 固定表名 取表，缺表会抛出 ValueError：

表名（`name`）	说明与主要字段
`bore_table`	钻孔表。需 bore_number``（钻孔编号）、``bore_top``（孔口标高）。可选 ``foundation_bottom_depth``（基础埋深，``GeoResults.FoundationDepth）；用于推算基底标高。
`layer_table`	地层表。需 `bore_number`、``layer_bottom_depth``（层底深度）。
`soil_test_table`	常规土工试验表。湿陷性表中的每个试样须能在此表匹配 `bore_number` + `sample_number`，并读取 `sample_top_depth`；`sample_length` 为空时按 0.2 m 处理。
`loess_collapsibility_table`	黄土湿陷性表。需 `bore_number`、`sample_number`、``self_weight_collapsibility_coefficient``（自重湿陷系数）、``collapsibility_coefficient``（湿陷系数）；上述字段不得为空。

字段名 / 标题以 GeoMaterialProps 等标准术语为准；GDIM 读表时建议使用与平台一致的 table_fields 映射。

计算规则说明

基底标高：若钻孔表给出 foundation_bottom_depth，则基底标高 = 孔口标高 − 基础埋深；否则默认 **孔口标高 − 1.5 m**（控制台会打印提示）。
自重湿陷量：使用完整一维剖面，自天然地面起算代表厚度与自重湿陷系数；分区修正系数 β₀ 由 area 决定。
湿陷量：在基底标高以下参与湿陷的代表土层上，按规范分段（深度边界 5 / 10 / 20 / 25 m）求 α、β 后累计；湿陷类型、等级由内部 loessCal 判定。
数据校验：湿陷性表试样在常规试验表中找不到、或关键系数为空时，模块抛出 ValueError 并指明钻孔/样品编号。

输出结构（OutputTableCollection）

集合 name 为 CollapsibilityTable，包含：

主表 single_line_table``（单行结果表，主键 ``GeoResults.ProfileNumber / 探井号）：孔口高程、基底高程、β₀、总自重湿陷量、湿陷类型、总湿陷量、湿陷等级等。
子表 1 ``multi_line_table1``（湿陷类型计算表）：各样自重湿陷系数、代表厚度、分样自重湿陷量。
子表 2 ``multi_line_table2``（湿陷等级计算表）：各样湿陷系数、代表厚度、α、β、分样湿陷量。

参数说明

Collapsibility 参数一览
参数名	类型	默认值	说明
`tables`	`TableCollection \| None`	`None`	输入四表集合；赋值后写入 `InputTables`。也可直接设置 `InputTables` 端口。
`area`	`"陇西地区" \| "陇东、陕北、晋西地区" \| "关中地区" \| "其它地区"`	`"陇西地区"`	湿陷性黄土工程地质分区，影响 β₀ 及 α、β 查表。

快速上手示例：接读表模块输出

from gdisdk.modules.geoSurvey import Collapsibility
from gdisdk.modules.readers import GdimTableReader

read_table = GdimTableReader(mname="ReadLoessTables")
read_table.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
read_table.table_fields = {
    "bore_table": ["bore_number", "bore_top", "foundation_bottom_depth"],
    "layer_table": ["bore_number", "layer_bottom_depth"],
    "soil_test_table": ["bore_number", "sample_number", "sample_top_depth", "sample_length"],
    "loess_collapsibility_table": [
        "bore_number",
        "sample_number",
        "self_weight_collapsibility_coefficient",
        "collapsibility_coefficient",
    ],
}
read_table.execute()
tables = read_table.OutputTables.data

mod = Collapsibility(mname="LoessColl")
mod.area = "关中地区"
mod.InputTables = tables
mod.execute()

result = mod.OutputTableCollection.data
if result is not None:
    summary = result.get_table("single_line_table")

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.geoSurvey import Collapsibility
from gdisdk.modules.readers import GdimTableReader

pipe = PipeLine(app_name="LoessCollDemo", app_title="黄土湿陷性计算示例")

reader = GdimTableReader(mname="ReadLoessTables")
reader.table_fields = {
    "bore_table": ["bore_number", "bore_top", "foundation_bottom_depth"],
    "layer_table": ["bore_number", "layer_bottom_depth"],
    "soil_test_table": ["bore_number", "sample_number", "sample_top_depth", "sample_length"],
    "loess_collapsibility_table": [
        "bore_number",
        "sample_number",
        "self_weight_collapsibility_coefficient",
        "collapsibility_coefficient",
    ],
}

coll = Collapsibility(mname="LoessColl")
coll.area = "陇西地区"

pipe.add_module(reader)
pipe.add_module(coll)
reader.OutputTables >> coll.InputTables
pipe.run()

out = coll.OutputTableCollection.data

Note

输出为 TableCollection``（1 主表 + 2 子表），下游可按 ``single_line_table / multi_line_table1 / multi_line_table2 分别写 DocData 或入库。

更多信息

Liquefaction

模块简介与适用场景

Liquefaction 根据标准地层、钻孔地层、标贯原位测试及黏粒含量统计，按 GB 50011 相关条文完成 液化初判、详判，并汇总各孔 液化指数 IlE 与液化等级。
岩土类型由标准地层表中的岩土名称经 map_material_for_cal(..., "for_liquefaction") 映射为砂土、粉土等；标准地层中 既无砂土也无粉土 时模块不计算，OutputTableCollection 为 None。
可与 SeismicDesignParameters 等模块配合：设防烈度、地震分组等也可在 UI 中手工指定，详见「参数说明」。
典型场景：勘察成果中批量输出液化评价表；pipeline 中接 GdimTableReader 读入勘探表、标贯表与标准地层后一键计算。

端口说明

输入端口
- InputTables：TableCollection，须含地层表、钻孔表、标贯表（表 name 见「输入表要求」）。可通过参数 tables 赋值。
- InputLayerOrderTables：TableCollection，须含标准地层表。可通过参数 layer_order_tables 赋值。
- InputClayStatTable：TableData 或 TableCollection``（常规试验统计表，黏粒含量 **层平均值**）。可选；未接时砂土/粉土黏粒含量按 **3.0%** 参与计算。可通过参数 ``clay_stat_table 赋值。
输出端口
- OutputTableCollection：TableCollection``（主表 + 2 张子表，``name 为 LiquefactionTable）。输入缺失、必需表未找到、无砂/粉土、或无法构造黏粒样品数据时为 None。

execute() 的返回值与 OutputTableCollection 一致。

输入表要求

模块通过 TableCollection.get_table(...) 按 固定表名或中文标题 取表，缺表时 OutputTableCollection 为 ``None``（不抛错）：

表名（`name`） / 备选标题	说明与主要字段
`standard_layer_table` / `场地地层层序`	标准地层表。需 `layer_number`、`material_name`、``geological_age_symbol``（用于 Q4 判定）。
`layer_table` / `地层表`	地层表。需 `bore_number`、`layer_number`、`layer_bottom_depth`。
`bore_table` / `勘探点表`、`钻孔一览表`	钻孔表。需 `bore_number`、``bore_top``（孔口标高）。
`spt_table` / `标贯`、`标准贯入表`	标贯表。需 `bore_number`、`test_point_top_depth`、`penetration_depth`、`blow_count`；贯入深度大于 3 时按厘米换算为米。

常规试验统计表（InputClayStatTable）

列：layer_number``（或 ``layer_num）、clay_content；若有 statistics_item 列则只取 平均值 行。
模块按钻孔地层为砂土/粉土分层生成黏粒样品；统计表缺层时砂土/粉土默认 3.0%；标贯与黏粒按深度匹配，匹配不上时详判侧亦按 3.0% 处理（粉土详判另有规范阈值跳过逻辑，见源码 liquefactionCal 调用处）。

计算规则说明

判别深度：自孔口向下截取 ``liq_just_depth``（20 m 或 15 m）范围内的地层参与液化分析。
水位与基底：``dw = 孔口标高 − anti_float_water_level``（小于 0 取 0）；``db = 孔口标高 − f_bottom_elev``（小于 2 m 取 2 m）。
6 度 + 特殊建筑：设防 6 度 且 ``is_special_bld=True``（对液化沉陷敏感的乙类建筑）时，内部按 7 度 参与液化判别。
初判 / 详判：初判针对与地下水接触的砂土、粉土层；详判基于标贯实测击数与临界值 Ncr，并累计液化指数、给出折减系数；核心算法在 gdi.geocal.liquefactionCal。
控制台输出：执行过程会打印中间剖面、标贯与黏粒匹配等信息，便于本地调试。

输出结构（OutputTableCollection）

集合 name 为 LiquefactionTable，包含：

主表 single_line_table``（单行结果表，主键 ``GeoResults.ProfileNumber / 孔号）：``liqClass``（IlE 与液化等级）、``needJustifyLiq``（报告用：该孔需判别液化的层号列表）。
子表 1 multi_line_table1``（液化判别表·初判）：层号、d0、覆盖层厚度 du、地下水位 dw、基础埋深 db、黏粒含量及初判公式项与 ``conclusion1。
子表 2 ``multi_line_table2``（液化判别表·详判）：试验深度、N0、Ncr、实测 N63.5、详判结论、液化指数 IlE、折减系数 α 等。

参数说明

Liquefaction 参数一览
参数名	类型	默认值	说明
`tables`	`TableCollection \| None`	`None`	勘探相关三表集合；赋值后写入 `InputTables`。
`layer_order_tables`	`TableCollection \| None`	`None`	标准地层表集合；赋值后写入 `InputLayerOrderTables`。
`clay_stat_table`	`TableData \| TableCollection \| None`	`None`	常规试验统计表；赋值后写入 `InputClayStatTable`。
`liq_just_depth`	`20 \| 15`	`20`	液化判别深度（m），自孔口向下。
`seismic_intensity`	见 UI 选项（6～9 度及对应加速度）	`7度（0.10g）`	抗震设防烈度。
`is_special_bld`	`bool`	`False`	是否特殊类型建筑（对液化沉陷敏感的乙类）；6 度时会按 7 度判别。
`seismic_group`	`1 \| 2 \| 3`	`3`	设计地震分组（第一/二/三组）。
`anti_float_water_level`	`float`	`10000.0`	抗浮水位高程（m）；与孔口标高换算地下水位深度。
`f_bottom_elev`	`float`	`0.0`	基础底面高程（m）；与孔口标高换算基础埋深。

快速上手示例：接读表模块输出

from gdisdk.modules.geoSurvey import Liquefaction
from gdisdk.modules.readers import GdimTableReader

read_tables = GdimTableReader(mname="ReadLiqMain")
read_tables.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
read_tables.table_fields = {
    "bore_table": ["bore_number", "bore_top"],
    "layer_table": ["bore_number", "layer_number", "layer_bottom_depth"],
    "spt_table": [
        "bore_number",
        "test_point_top_depth",
        "penetration_depth",
        "blow_count",
    ],
}
read_tables.execute()
main_tables = read_tables.OutputTables.data

read_std = GdimTableReader(mname="ReadStdLayer")
read_std.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
read_std.table_fields = {
    "standard_layer_table": [
        "layer_number",
        "material_name",
        "geological_age_symbol",
    ],
}
read_std.execute()
std_tables = read_std.OutputTables.data

mod = Liquefaction(mname="LiqCal")
mod.liq_just_depth = 20
mod.seismic_intensity = "7度（0.10g）"
mod.seismic_group = 3
mod.anti_float_water_level = 10000.0
mod.f_bottom_elev = 0.0
mod.InputTables = main_tables
mod.InputLayerOrderTables = std_tables
mod.execute()

result = mod.OutputTableCollection.data
if result is not None:
    summary = result.get_table("single_line_table")

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.geoSurvey import Liquefaction
from gdisdk.modules.readers import GdimTableReader

pipe = PipeLine(app_name="LiqDemo", app_title="液化判别示例")

reader_main = GdimTableReader(mname="ReadLiqMain")
reader_main.table_fields = {
    "bore_table": ["bore_number", "bore_top"],
    "layer_table": ["bore_number", "layer_number", "layer_bottom_depth"],
    "spt_table": [
        "bore_number",
        "test_point_top_depth",
        "penetration_depth",
        "blow_count",
    ],
}

reader_std = GdimTableReader(mname="ReadStdLayer")
reader_std.table_fields = {
    "standard_layer_table": [
        "layer_number",
        "material_name",
        "geological_age_symbol",
    ],
}

liq = Liquefaction(mname="LiqCal")
liq.seismic_intensity = "8度（0.20g）"
liq.seismic_group = 2
liq.anti_float_water_level = 98.5
liq.f_bottom_elev = 96.0

pipe.add_module(reader_main)
pipe.add_module(reader_std)
pipe.add_module(liq)
reader_main.OutputTables >> liq.InputTables
reader_std.OutputTables >> liq.InputLayerOrderTables
pipe.run()

out = liq.OutputTableCollection.data

Note

参与液化的钻孔以 标贯表中有完整击数记录 的 bore_number 为准；单孔标贯点少于 2 个且位于水位以下时可能跳过详判。
anti_float_water_level 默认 10000.0 时地下水位深度 dw 取 0；有抗浮水位时请改为实际高程。
输出为 TableCollection``（1 主表 + 2 子表），下游可按 ``single_line_table / multi_line_table1 / multi_line_table2 写 DocData 或入库。

更多信息

WaterSoilCorrosion

模块简介与适用场景

WaterSoilCorrosion 依据 GB 50021 对水样或土样的化学分析数据进行腐蚀性分级评价。
重要：输入既可以是单张分析表（TableData），也可以是读表模块输出的 TableCollection，无需先手动拆表。
典型场景：在 pipeline 中批量评价水质/土化学分析的腐蚀性，并从多个输出端口获取环境类型、Cl⁻、pH 或渗透性等结果。评价模式、必填列、列映射及参数见下文。

端口说明

输入端口
- InputTable：水/土化学分析数据（TableData 或 TableCollection）。详见「输入数据形式」。
**输出端口**（均为 TableCollection；有效端口由 evaluation 决定，无输入表时均为 None）
- OutputEnvResult：环境类型（Ⅰ/Ⅱ/Ⅲ 类）分项及综合结果。
- OutputClResult：Cl⁻ 对混凝土钢筋腐蚀性的评价。
- OutputPHResult：pH 评价（仅 evaluation="soil"）。
- OutputPermeabilityResult：渗透性评价（仅 evaluation="water"）。

execute() 的返回值为 OutputEnvResult 对应的 ``TableCollection``（与其它输出端口同步写入）。

输入数据形式

单表（``TableData``）：输入即为一张水/土化学分析表，模块直接校验列并重命名后评价。
多表（``TableCollection``）：常见于 GdimTableReader.OutputTables 等上游输出。模块按 evaluation 在集合中查找分析表：
- 水评价依次尝试：water_chemical_analysis_table → water_soil_quality_test_table
- 土评价依次尝试：soil_chemical_analysis_table → water_soil_quality_test_table
若表名/标题不在上述候选列表中，请设置 data_table_name 为实际表名或表标题。

评价模式与必填列

evaluation="water"：浓度单位一般为 mg/L；需能解析到以下列（字段名 / 标题见 GeoMaterialProps）：

语义	字段名	标题示例
取样编号	`sample_number`	取样编号
Cl⁻	`cl_negative`	氯离子Cl⁻
SO₄²⁻	`so42_negative`	硫酸盐SO₄²⁻
Mg²⁺	`mg2_positive`	镁盐Mg²⁺
NH₄⁺	`nh4_positive`	铵盐NH₄⁺
OH⁻	`oh_negative`	苛性碱OH⁻
总矿化度	`total_mineralization`	总矿化度
侵蚀性 CO₂	`corrosive_carbon_dioxide`	侵蚀性CO₂
HCO₃⁻	`hco3_negative`	HCO₃⁻
pH	`ph`	PH值

evaluation="soil"：浓度单位一般为 mg/kg；需：

语义	字段名	标题示例
取样编号	`sample_number`	取样编号
地层编号	`layer_number`	地层编号
pH	`ph`	PH值
Cl⁻	`cl_negative`	氯离子Cl⁻
SO₄²⁻	`so42_negative`	硫酸盐SO₄²⁻
Mg²⁺	`mg2_positive`	镁盐Mg²⁺

**列映射**（water_columns_map / soil_columns_map）：
- 键：输入 TableData 列的字段名或列标题。
- 值：目标 GeoMaterialProps 的字段名（如 "cl_negative"）**或** 标题（如 "氯离子Cl⁻"）。
- 未配置映射时，模块按 GeoMaterialProps 字段名优先、标题次之 自动匹配。
- 列缺失或数据不满足内部校验时，模块会抛出 ValueError 并指明缺失列。

参数说明

WaterSoilCorrosion 参数一览
参数名	类型	默认值	说明
`table`	`TableData \| TableCollection \| None`	`None`	水/土化学分析数据；类型与选取规则见「输入数据形式」。也可通过 `InputTable` 端口传入。
`evaluation`	`"water" \| "soil"`	`"water"`	水腐蚀性或土腐蚀性。
`env_type`	`"class1" \| "class2" \| "class3"`	`"class1"`	环境类型，对应 Ⅰ / Ⅱ / Ⅲ 类。
`soil_type_Cl`	`"A" \| "B"`	`"A"`	土评价时 Cl⁻ 路径的土类划分（A/B，与规范土类描述一致，见 UI 选项说明）。
`soil_type_PH`	`"A" \| "B"`	`"A"`	土评价时 pH 路径的透水性分类（强透水/弱透水土层）。
`data_table_name`	`str \| None`	`None`	当 `InputTable` 为 `TableCollection` 时，指定含分析数据的表名或表标题。未设置时按「输入数据形式」中的候选表名自动查找。
`water_columns_map`	`dict[str, str] \| None`	`None`	水评价列映射（键/值规则及必填列见「评价模式与必填列」）。
`soil_columns_map`	`dict[str, str] \| None`	`None`	土评价列映射（规则同 `water_columns_map`）。

快速上手示例 1：单表输入（列名已为标准字段名）

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.geoSurvey import WaterSoilCorrosion

table = TableData(
    {
        "sample_number": ["W1"],
        "cl_negative": [50.0],
        "so42_negative": [200.0],
        "mg2_positive": [300.0],
        "nh4_positive": [10.0],
        "oh_negative": [5.0],
        "total_mineralization": [500.0],
        "corrosive_carbon_dioxide": [10.0],
        "hco3_negative": [2.0],
        "ph": [7.2],
    },
    name="water_chem",
    title="水化学分析",
)

mod = WaterSoilCorrosion(mname="WaterCorrosion")
mod.evaluation = "water"
mod.env_type = "class1"
mod.InputTable = table
mod.execute()

env_tables = mod.OutputEnvResult.data
cl_tables = mod.OutputClResult.data
perm_tables = mod.OutputPermeabilityResult.data

快速上手示例 2：TableCollection 输入（接读表模块输出）

from gdisdk.dataclass.terminologies import GeoMaterialProps
from gdisdk.modules.geoSurvey import WaterSoilCorrosion
from gdisdk.modules.readers import GdimTableReader

# 读表模块输出 TableCollection，内含水化学分析表
read_table = GdimTableReader(mname="ReadWaterChem")
read_table.table_fields = {
    "water_chemical_analysis_table": [
        "sample_number",
        "cl_negative",
        "so42_negative",
        "mg2_positive",
        "nh4_positive",
        "oh_negative",
        "total_mineralization",
        "corrosive_carbon_dioxide",
        "hco3_negative",
        "ph",
    ],
}
read_table.execute()
tables = read_table.OutputTables.data

mod = WaterSoilCorrosion(mname="WaterCorrosion")
mod.evaluation = "water"
mod.env_type = "class1"
mod.InputTable = tables
mod.execute()

# 若表名不在默认候选列表，可显式指定：
# mod.data_table_name = "勘探孔水土质试验表"
# 若列标题与标准字段不一致，可配置列映射：
# mod.water_columns_map = {
#     "样品编号": GeoMaterialProps.SampleNumber.value,
#     "Cl^-": GeoMaterialProps.Cl.value,
# }

在 pipeline 中的使用方式

将上游输出接入 InputTable``（例如 ``GdimTableReader.OutputTables >> water_corrosion.InputTable），配置评价参数后 pipe.run()；结果从 OutputEnvResult 等端口读取即可（可使用 gdisdk 包路径）。

Note

输出为 ``TableCollection``（主表 + 子表结构），便于在报表或下游模块中继续处理。

更多信息