modules.pileFoundation 模块帮助

本章节包含 modules.pileFoundation 包中桩基相关计算模块的使用说明和示例，例如：

依据土工试验指标计算桩侧阻力特征值 qsik``（``SkinCapacityByTest，JGJ 94-2008 第 5.3.5 条）
依据土工试验指标与层深区间计算桩端阻力特征值 qpk``（``BaseCapacityByTest，JGJ 94-2008 第 5.3.5 条）
其它桩基模块（详见 modules.pileFoundation）

SkinCapacityByTest

模块简介与适用场景

SkinCapacityByTest 对 MaterialTable 中每一行岩土，按 JGJ 94-2008《建筑桩基技术规范》第 5.3.5 条 经验表，由液性指数、含水率与液限、孔隙比、标贯/动探击数、单轴抗压强度等 试验指标 计算 桩侧阻力特征值 ``qsik``（kPa）。
同时输出三种成桩工艺对应的建议值及字符串说明：**混凝土预制桩**（concrete）、**泥浆护壁钻（冲）孔桩**（mud）、**干作业钻孔桩**（dry）。
典型场景：标准地层表已汇总各层土工试验数据，需在 pipeline 中批量得到侧阻供桩基设计或报表；常与 ConvertToMaterialTable 串联。

端口说明

输入端口
- InputMaterials：材料表（MaterialTable）。也可通过参数 material_table 传入（等价写入 InputMaterials）。
输出端口
- OutputResults：结果表（TableData，name 为 skin_capacity_by_test_qsik）。若 InputMaterials 为 None，则为 None。

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

输入字段要求

模块通过 RequiredColumnCheck 校验：

必须存在 GeoMaterialProps.MaterialName``（``material_name / 岩土名称）
**至少存在其一**（列级 OR）：LiquidityIndex、NaturalWaterContent、LiquidLimit、VoidRatio、SPTNumber、DPTNumber、SaturateUCS、UCS

可选列 GeoMaterialProps.LayerNumber 会原样带入输出；material_id 来自材料表索引。

岩土名称经 for_skin_bc 映射（风化描述会参与岩石类判定）。**表结构**只需包含与本项目岩土类型可能用到的指标列；**每一行**须具备该岩土类型计算所需的非空指标，否则该行 qsik 为空，数值列与三个 *_str 均为 None。

按岩土类型的行级指标（概要）

映射后类型（示例）	该行需具备的主要指标
填土、淤泥、淤泥质土	无额外指标（取规范建议区间中值）
黏性土	``liquidity_index``（液性指数）
红黏土	`natural_moisture_content`、liquid_limit``（用于含水比 ``aw = w / w_L）
粉土	``void_ratio``（孔隙比）
粉细砂、中砂、粗砂	``spt_number``（标贯击数）
砾砂、圆砾和角砾、碎石和卵石	``dpt_number``（动探击数）
岩石（全风化 / 强风化等）	`saturated_uniaxial_compressive_strength` 或 uniaxial_compressive_strength``（MPa）；全风化还需 ``spt_number，强风化还需 `dpt_number`；强度区间与岩性名称共同决定查表分支

无法映射或归类为其他时，该行无法计算。具体分段、插值与 < / > / 区间字符串规则与内部 cal_pile_skin_capacity_qsik 及规范表一致。

输出字段说明（OutputResults）

material_id、layer_number、material_name
concrete / concrete_str：混凝土预制桩侧阻（kPa）
mud / mud_str：泥浆护壁钻（冲）孔桩侧阻（kPa）
dry / dry_str：干作业钻孔桩侧阻（kPa）

无法计算时，数值列与三个 *_str 均为 None。可计算时，字符串列可能为数值、区间（如 60~80）或边界形式，数值列为对应建议计算值。

参数说明

SkinCapacityByTest 参数一览
参数名	类型	默认值	说明
`material_table`	`MaterialTable \| None`	`None`	输入材料表；赋值后写入 `InputMaterials`。也可直接设置 `InputMaterials` 端口。

快速上手示例：材料表计算 qsik

from gdisdk.dataclass.geoProfiles import MaterialTable
from gdisdk.dataclass.terminologies import GeoMaterialProps as GProps
from gdisdk.modules.pileFoundation import SkinCapacityByTest

materials = MaterialTable(
    {
        GProps.MaterialID: [0, 1, 2],
        GProps.LayerNumber: ["1", "2", "3"],
        GProps.MaterialName: ["黏性土", "砂土", "粉土"],
        GProps.LiquidityIndex: [0.4, None, None],
        GProps.SPTNumber: [None, 12, None],
        GProps.VoidRatio: [None, None, 0.85],
    }
)

mod = SkinCapacityByTest(mname="SkinCapacityByTest")
mod.InputMaterials = materials
mod.execute()

result = mod.OutputResults.data

快速上手示例：接 ConvertToMaterialTable

from gdisdk.dataclass.terminologies import GeoMaterialProps as GProps
from gdisdk.modules.converters import ConvertToMaterialTable
from gdisdk.modules.pileFoundation import SkinCapacityByTest

conv = ConvertToMaterialTable(mname="ConvertMaterial")
conv.column_name_map = {
    "地层编号": GProps.LayerNumber,
    "岩土名称": GProps.MaterialName,
    "液性指数": GProps.LiquidityIndex,
    "天然含水率w": GProps.NaturalWaterContent,
    "液限": GProps.LiquidLimit,
    "孔隙比": GProps.VoidRatio,
    "标贯击数": GProps.SPTNumber,
    "动探击数": GProps.DPTNumber,
    "饱和单轴抗压强度": GProps.SaturateUCS,
    "单轴抗压强度": GProps.UCS,
}
# conv.InputTable = standard_layer_table
conv.execute()
materials = conv.OutputMaterialTable.data

mod = SkinCapacityByTest(mname="SkinCapacityByTest")
mod.InputMaterials = materials
mod.execute()
qsik_table = mod.OutputResults.data

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.converters import ConvertToMaterialTable
from gdisdk.modules.pileFoundation import SkinCapacityByTest

pipe = PipeLine(app_name="SkinQsikDemo", app_title="桩侧阻力特征值计算")

convert = ConvertToMaterialTable(mname="ConvertMaterial")
calc = SkinCapacityByTest(mname="SkinCapacityByTest")

# links = reader.OutputTable >> convert.InputTable
# links = convert.OutputMaterialTable >> calc.InputMaterials
# pipe.add_module(convert)
# pipe.add_module(calc)
# pipe.run()
# qsik_table = calc.OutputResults.data

BaseCapacityByTest

模块简介与适用场景

BaseCapacityByTest 对 MaterialTable 中每一行岩土，按 JGJ 94-2008《建筑桩基技术规范》第 5.3.5 条 经验表，由 层顶/层底深度 与液性指数、孔隙比、标贯/动探击数、单轴抗压强度等指标，计算 桩端阻力特征值 ``qpk``（kPa）。
根据 min_layer_top_depth、max_layer_bottom_depth 判定桩长分段（预制桩、泥浆护壁桩、干作业桩的分段规则不同），同一行可能对多个桩长档给出建议值；concrete_str / mud_str / dry_str 中多个桩长档以逗号分隔，并带桩长区间标注（如 (L<=9)）。
同时输出 混凝土预制桩、泥浆护壁钻（冲）孔桩、干作业钻孔桩 三类端阻数值与字符串说明。
典型场景：持力层或各岩土层已汇总深度与试验指标，需在 pipeline 中批量估算端阻；常与 ConvertToMaterialTable 串联。

端口说明

输入端口
- InputMaterials：材料表（MaterialTable）。也可通过参数 material_table 传入。
输出端口
- OutputResults：结果表（TableData，name 为 base_capacity_by_test_qpk）。若 InputMaterials 为 None，则为 None。

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

输入字段要求

模块通过 RequiredColumnCheck 校验：

必须存在 ``GeoMaterialProps.MaterialName``（岩土名称）
必须存在 GeoMaterialProps.MinLayerTopDepth``（``min_layer_top_depth / 最小层顶深度，m）
必须存在 GeoMaterialProps.MaxLayerBottomDepth``（``max_layer_bottom_depth / 最大层底深度，m）
**至少存在其一**（列级 OR）：LiquidityIndex、VoidRatio、SPTNumber、DPTNumber、SaturateUCS、UCS

可选列 LayerNumber 会带入输出。每一行还须 层顶、层底深度均非空，且 min_layer_top_depth < max_layer_bottom_depth``（否则内部计算返回 ``None 并可能发出警告）。

岩土名称经 for_base_bc 映射（风化描述参与岩石类判定）。**每一行**另须具备该岩土类型所需的非空试验指标，否则该行数值列与字符串列均为 None。

按岩土类型的行级指标（概要）

映射后类型（示例）	该行除深度外需具备的主要指标
黏性土	`liquidity_index`
粉土	`void_ratio`
粉砂	``spt_number``（分段查表）
细砂、中砂、粗砂、砾砂	`spt_number`
角砾和圆砾、碎石和卵石	`dpt_number`
岩石（全风化 / 强风化等）	`saturated_uniaxial_compressive_strength` 或 uniaxial_compressive_strength``（MPa）；全风化还需 ``spt_number，强风化还需 `dpt_number`

无法映射或归类为其他时，该行数值列与字符串列均为 None。泥浆护壁桩、干作业桩在 桩端深度 < 5 m 时，对应桩型的数值列与字符串列为 None，同层其他桩型仍可有值。

输出字段说明（OutputResults）

material_id、layer_number、material_name
concrete / concrete_str：混凝土预制桩端阻（kPa）
mud / mud_str：泥浆护壁钻（冲）孔桩端阻（kPa）
dry / dry_str：干作业钻孔桩端阻（kPa）

无法计算时，数值列与三个 *_str 均为 None。可计算且跨多个桩长档时，字符串列可能为多行文本，数值列一般为各档建议值的 **平均值**（与 SkinCapacityByTest 侧阻的字符串形式可能不同）。某一桩型不在规范桩长范围内时，仅该桩型的数值列与字符串列为 None。

参数说明

BaseCapacityByTest 参数一览
参数名	类型	默认值	说明
`material_table`	`MaterialTable \| None`	`None`	输入材料表；赋值后写入 `InputMaterials`。也可直接设置 `InputMaterials` 端口。

快速上手示例：材料表计算 qpk

from gdisdk.dataclass.geoProfiles import MaterialTable
from gdisdk.dataclass.terminologies import GeoMaterialProps as GProps
from gdisdk.modules.pileFoundation import BaseCapacityByTest

materials = MaterialTable(
    {
        GProps.MaterialID: [0, 1, 2],
        GProps.LayerNumber: ["1", "2", "3"],
        GProps.MaterialName: ["黏性土", "砂土", "粉土"],
        GProps.MinLayerTopDepth: [8.0, 12.0, 20.0],
        GProps.MaxLayerBottomDepth: [12.0, 20.0, 28.0],
        GProps.LiquidityIndex: [0.4, None, None],
        GProps.SPTNumber: [None, 12, None],
        GProps.VoidRatio: [None, None, 0.85],
    }
)

mod = BaseCapacityByTest(mname="BaseCapacityByTest")
mod.InputMaterials = materials
mod.execute()

result = mod.OutputResults.data

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.converters import ConvertToMaterialTable
from gdisdk.modules.pileFoundation import BaseCapacityByTest

pipe = PipeLine(app_name="BaseQpkDemo", app_title="桩端阻力特征值计算")

convert = ConvertToMaterialTable(mname="ConvertMaterial")
calc = BaseCapacityByTest(mname="BaseCapacityByTest")

# links = reader.OutputTable >> convert.InputTable
# links = convert.OutputMaterialTable >> calc.InputMaterials
# pipe.add_module(convert)
# pipe.add_module(calc)
# pipe.run()
# qpk_table = calc.OutputResults.data

更多信息

API 参考 - modules 包
完整类定义与参数说明（pileFoundation）
材料表转换见 modules.converters 模块帮助中的 ConvertToMaterialTable