modules.geoSurvey 模块帮助

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

• 地震参数查询与设防参数计算

• 地基液化、湿陷、水土腐蚀性评价等（详见 modules.geoSurvey）

SeismicDesignParameters

模块简介与适用场景

• SeismicDesignParameters 根据点位经纬度查询地震动参数，并按 GB 18306 计算设防参数；输出字段见下文「输出字段说明」。

• 典型适用场景：

  • 在勘察成果/设计输入中，需要快速获取项目区的地震动参数与设防信息；

  • 在自动化 pipeline 中，根据钻孔/场地坐标批量补全地震参数字段；

  • 作为液化、场地类别等后续分析的输入条件之一。

端口说明

• 输入端口

  • InputPoint：点位信息（SingleResult），至少含经纬度（GeneralProps.Longitude / GeneralProps.Latitude）；亦可通过参数 point 传入。

  • InputToken：鉴权 Token；亦可通过参数 token / host 传入，或由 pipeline 统一配置。

• 输出端口

  • OutputResult：地震设计参数结果（SingleResult，包含若干 UnitResult；见下文 “输出字段说明”）

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

from gdisdk.dataclass.results import SingleResult, UnitResult
from gdisdk.dataclass.terminologies import GeneralProps
from gdisdk.modules.geoSurvey import SeismicDesignParameters

# 1) 构造点位（经纬度）
point = SingleResult(
    [
        UnitResult(
            name=GeneralProps.Longitude,
            title=GeneralProps.Longitude.title,
            value=104.0668,  # 成都附近示例，经度
        ),
        UnitResult(
            name=GeneralProps.Latitude,
            title=GeneralProps.Latitude.title,
            value=30.5728,  # 成都附近示例，纬度
        ),
    ]
)

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

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

Note

• 若查询失败（例如坐标不在服务范围、坐标系不一致、token 无效等），模块会给出告警，并输出字段为 None 的结果。

• 点位坐标建议使用 经纬度（WGS84 / EPSG:4326）；若你的点位来自投影坐标，请先做坐标转换再查询。

输出字段说明（OutputResult）

OutputResult 为 SingleResult，通常包含以下字段（以 GeoResults 命名）：

• GeoResults.EffectivePeakAcceleration：有效峰值加速度（epa / (a_{max})）

• GeoResults.CharacteristicPeriodOfSeismicAccelerationResponseSpectrum：地震加速度反应谱特征周期（tg / (T_g)）

• GeoResults.SeismicDesignIntensity：地震设防烈度

• GeoResults.SeismicDesignGroup：地震分组（第一组/第二组/第三组）

参数说明

SeismicDesignParameters 参数一览

参数名	类型	默认值	说明
point	SingleResult | None	None	点位信息（经纬度）。也可通过输入端口 InputPoint 传入。
token	str | None	None	鉴权 token（推荐直接使用 GDIM 登录 token）。也可通过 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.results import SingleResult, UnitResult
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 = SingleResult(
    [
        UnitResult(name=GeneralProps.Longitude, title=GeneralProps.Longitude.title, value=104.0668),
        UnitResult(name=GeneralProps.Latitude, title=GeneralProps.Latitude.title, value=30.5728),
    ]
)

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

result = mod.OutputResult.data

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``（主表 + 子表结构），便于在报表或下游模块中继续处理。

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（geoSurvey）