modules.geoSurvey 模块帮助

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

地震参数查询与设防参数计算
地基液化、湿陷、水土腐蚀性评价等（详见 modules.geoSurvey）

SeismicDesignParameters

模块简介与适用场景

SeismicDesignParameters 用于根据点位的经纬度，查询地震动参数（如有效峰值加速度 (a_{max}) 与特征周期 (T_g)），并按规范规则计算设防参数（设防烈度、地震分组等）。
典型适用场景：
- 在勘察成果/设计输入中，需要快速获取项目区的地震动参数与设防信息；
- 在自动化 pipeline 中，根据钻孔/场地坐标批量补全地震参数字段；
- 作为液化、场地类别等后续分析的输入条件之一。

端口说明

输入端口
- InputPoint：点位信息（SingleResult），至少包含经纬度两个字段（GeneralProps.Longitude / GeneralProps.Latitude）
- InputToken：鉴权信息（Token；来自 GDIM 登录 token；也可直接在构造函数中传入 token / host）
输出端口
- 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",
    token="你的GDIM Token",
    host=None,   # 可选；None 时使用默认 host（或由平台默认）
    point=point,
)

out = mod.execute()
print(out)

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", point=point)
pipe.add_module(mod)
pipe.run()

result = mod.OutputResult.data

WaterSoilCorrosion

模块简介与适用场景

WaterSoilCorrosion 根据《岩土工程勘察规范》GB 50021 相关条文，对水或土的化学分析数据进行腐蚀性分级评价（混凝土、钢结构等常用判别路径在实现中按规范表格与模块内逻辑计算）。
水样输入浓度单位一般为 mg/L**（与勘察水质分析常用表示一致）；**土样 一般为 mg/kg。若表中列名与标准字段不一致，可通过 water_columns_map / soil_columns_map 映射，或不传映射由模块按 GeoMaterialProps 的 字段名优先、标题次之 自动匹配列。
典型场景：水质/土化学分析表批量评价腐蚀性；在 pipeline 中接在读表或转换模块之后输出多张结果表（环境类型法、Cl⁻法、渗透性法或 pH 法等）。

端口说明

输入端口
- InputTable：水/土化学分析数据（TableData）。
**输出端口**（均为 TableCollection；无输入表时全部为 None）
- OutputEnvResult：按 **环境类型**（Ⅰ类、Ⅱ类、Ⅲ类）对腐蚀介质分项评价及综合结果。
- OutputClResult：按 氯离子 Cl⁻ 对混凝土钢筋腐蚀性的评价结果。
- OutputPHResult：仅 土腐蚀性**（``evaluation=”soil”``）时有效——按 **pH 的评价结果；水评价时该端口为 None。
- OutputPermeabilityResult：仅 水腐蚀性**（``evaluation=”water”``）时有效——按 **渗透性 相关判据的评价结果；土评价时该端口为 None。

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

评价模式与必填列

evaluation="water" 时，需能解析到以下语义列（字段名见 GeoMaterialProps）：取样编号、Cl⁻、SO₄²⁻、Mg²⁺、NH₄⁺、OH⁻、总矿化度、侵蚀性 CO₂、HCO₃⁻、pH。
evaluation="soil" 时，需：取样编号、地层编号、pH、Cl⁻、SO₄²⁻、Mg²⁺。

列缺失或数据不满足内部校验时，底层评价函数会抛出 ``ValueError``（例如环境类型法缺少必需列等）。

参数说明

WaterSoilCorrosion 参数一览
参数名	类型	默认值	说明
`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 路径的透水性分类（强透水/弱透水土层）。
`water_columns_map`	`dict[str, str] \| None`	`None`	水评价列映射：键为表中列名或列标题，值为 `GeoMaterialProps` 取值或标题。
`soil_columns_map`	`dict[str, str] \| None`	`None`	土评价列映射，规则同 `water_columns_map`。

快速上手示例（水腐蚀性，列名已为标准字段名）

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(
    evaluation="water",
    env_type="class1",
)
mod.InputTable = table
mod.execute()

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

在 pipeline 中的使用方式

将上一模块的 TableData 接入 InputTable，设置 evaluation、env_type、土类参数等属性后 pipe.run()；结果从 OutputEnvResult 等端口读取即可（与 SeismicDesignParameters 类似，可使用 gdisdk 包路径）。

Note

输出为 ``TableCollection``（主表 + 子表结构），具体列名与标题由评价实现写入，便于在报表或下游模块中继续处理。
若需兼容中文列名的原始勘察表，优先配置 water_columns_map / soil_columns_map，避免自动匹配歧义。

更多信息