企业官网建设流程全解析

scirocco-pyclient 完整使用手册

一、包基础概述

1. 软件定位与核心功能

scirocco-pyclient是Scirocco 高性能流体/风环境仿真平台官方Python客户端SDK，用于远程调用Scirocco仿真服务，实现仿真任务全生命周期自动化，无需手动打开Scirocco桌面客户端。
Scirocco是专业CFD、城市风环境、建筑通风、光伏流场、热环境仿真软件，该Python包是平台唯一官方编程交互接口。

核心功能分类

1. 服务连接管理
   • HTTP/HTTPS、内网RPC两种协议连接Scirocco服务端
   • 账号密钥鉴权、token会话缓存、多服务实例并行连接
   • 连接健康检测、断线自动重连、SSL证书校验开关
2. 工程项目操作
   • 创建、复制、重命名、删除仿真工程
   • 批量读取工程列表、筛选工程（名称/创建时间/仿真类型）
   • 工程配置文件（.sci格式）读写、参数批量修改
3. 网格模块自动化
   • 上传CAD几何模型（STL/STEP/IGS）至服务端
   • 远程启动网格划分、设置全局/局部网格加密尺寸
   • 查询网格进度、导出网格质量报告、下载网格文件
4. 仿真求解调度
   • 配置边界条件、湍流模型、求解步数、收敛判定标准
   • 提交串行/并行分布式仿真任务（多GPU/多CPU集群）
   • 任务启停、暂停、终止、优先级调整、队列管理
5. 结果数据读写与后处理
   • 实时获取监控曲线（风速、压力、温度、阻力系数）
   • 批量导出切面云图、等值面、流线数据（CSV/VTK/TXT）
   • 读取仿真残差、收敛日志、节点数据、单元场变量
6. 批量自动化与脚本扩展
   • 循环批量参数化仿真（DOE正交试验、参数扫描）
   • 本地文件批量上传、仿真结果自动归档
   • 回调函数绑定任务状态、仿真完成自动触发数据分析
7. 资源与权限管控
   • 查询服务端算力、内存、GPU占用
   • 工程权限分配、任务日志导出、操作审计记录

2. 适用行业场景

建筑风环境、城市微气候、光伏阵列流场、隧道通风、暖通CFD、汽车外流场、工业设备散热仿真自动化。

二、完整安装教程

环境依赖要求

• Python版本：3.8 ~ 3.11（3.12存在兼容性bug，官方暂不支持）
• 系统：Windows10+/Linux Ubuntu20.04+/CentOS7+/macOS12+
• 依赖库：requests、numpy、pandas、pycryptodome、tqdm、vtk（自动附带安装）

方式1：PyPI标准安装（推荐）

# 稳定正式版pipinstallscirocco-pyclient--upgrade# 指定国内镜像加速pipinstallscirocco-pyclient-ihttps://pypi.tuna.tsinghua.edu.cn/simple

方式2：离线源码安装（内网无外网环境）

1. 从Scirocco服务端安装目录获取源码包scirocco-pyclient.tar.gz
2. 解压后进入目录执行：

python setup.pyinstall

方式3：开发调试版本

pipinstallscirocco-pyclient==dev--pre

验证安装是否成功

importscirocco_clientprint(scirocco_client.__version__)# 输出版本号即代表安装正常

三、核心语法、模块与全量参数说明

顶层模块结构

scirocco_client ├── Client # 主连接客户端（核心类） ├── Project # 工程操作类 ├── MeshTool # 网格划分工具类 ├── SolverTask # 仿真任务调度类 ├── ResultReader # 仿真结果读取类 ├── exceptions # 自定义异常集合 ├── enums # 枚举常量（仿真类型、湍流模型、边界类型） └── utils # 工具函数（文件上传、日志、参数转换）

1. 核心类：Client 连接客户端（最基础语法）

初始化构造函数完整参数

Client(host:str,# Scirocco服务端IP/域名，必填port:int,# 服务端口，默认8080；RPC端口50051username:str=None,# 登录账号password:str=None,# 登录密码api_key:str=None,# 密钥鉴权（企业集群推荐，替代账号密码）protocol:str="http",# 协议：http / https / grpcssl_verify:bool=True,# 是否校验SSL证书，内网测试可设Falsetimeout:int=30,# 请求超时时间(秒)max_retry:int=3,# 接口失败重试次数session_cache:bool=True# 缓存登录token，重复使用无需重新登录)

Client 常用核心方法

2. Project 工程操作类参数与语法

获取工程对象：

client=Client(host="192.168.1.100",port=8080,username="admin",password="123456")client.login()proj=client.get_project(proj_id="PROJ_202606001")

核心方法参数：

1. upload_geometry(file_path, unit="m")
   • file_path：本地几何文件路径（STL/STEP/IGS）
   • unit：几何单位 m/mm/cm
2. set_mesh_global_size(base_size, min_size_ratio)
   • base_size：全局基础网格尺寸(float)
   • min_size_ratio：最小网格与基础网格比例(0~1)
3. add_mesh_refinement(box_min, box_max, refine_size)
   局部加密盒：box_min=[x,y,z]、box_max=[x,y,z]加密区域坐标
4. set_boundary(bound_name, bnd_type, params: dict)
   bnd_type枚举：VELOCITY、PRESSURE_INLET、PRESSURE_OUTLET、WALL、SYMMETRY等
5. set_solver_config(model_type, iter_num, target_residual)
   model_type：k-epsilon、k-omega SST、RNG k-epsilon等湍流模型
   iter_num：最大迭代步数
   target_residual：收敛残差阈值（默认1e-6）
6. submit_task(gpu_num=0, priority=2)
   gpu_num：使用GPU数量，0=仅CPU；priority：1最高~5最低

3. SolverTask 任务对象参数

task=proj.submit_task()task.wait(timeout=None)# 阻塞等待仿真完成task.stop()# 终止任务task.pause()# 暂停task.get_status()# 返回状态：Pending/Running/Converged/Failedtask.get_residual_curve()# 获取残差数组

4. ResultReader 后处理读取参数

res=ResultReader(proj,task_id=task.task_id)# 导出切面数据data=res.extract_slice(plane="X",pos=5.0,variables=["Ux","Uy","Uz","P"])# 导出云图文件res.export_contour(file_path="./wind_slice.csv",plane="Z",resolution=200)# 获取全局监控值drag_coeff=res.get_monitor_value("Cd")

5. 枚举常量 enums 常用参数

fromscirocco_client.enumsimportSimType,TurbulenceModel,BoundaryType SimType.WIND_ENVIRONMENT# 建筑风环境仿真SimType.HEAT_TRANSFER# 热环境散热仿真TurbulenceModel.SST_K_OMEGA# SST k-ω模型（建筑风首选）BoundaryType.VELOCITY_INLET# 速度入口边界

四、8个完整可运行实际应用案例

案例1：基础连接+创建空白风环境工程

fromscirocco_clientimportClientfromscirocco_client.enumsimportSimType# 1. 初始化客户端并登录cli=Client(host="127.0.0.1",port=8080,username="admin",password="Scirocco@2026",protocol="http")cli.login()print("服务连接成功，服务状态：",cli.health_check())# 2. 新建建筑风环境仿真工程new_proj=cli.create_project(name="高层住宅风环境仿真",sim_type=SimType.WIND_ENVIRONMENT)print("新建工程ID：",new_proj.proj_id)# 3. 关闭连接cli.close()

案例2：上传建筑STEP几何+全局网格设置

fromscirocco_clientimportClient cli=Client("192.168.1.100",8080,"admin","123456")cli.login()proj=cli.create_project("商业综合体通风",sim_type="WIND_ENVIRONMENT")# 上传本地STEP建筑模型proj.upload_geometry(file_path=r"./building.step",unit="m")# 设置全局网格：基础尺寸2m，最小网格比例0.1proj.set_mesh_global_size(base_size=2.0,min_size_ratio=0.1)# 增加近建筑局部加密（加密尺寸0.5m）proj.add_mesh_refinement(box_min=[-50,-50,0],box_max=[80,80,120],refine_size=0.5)print("几何上传+网格配置完成")cli.close()

案例3：批量设置边界条件+配置SST湍流求解器

fromscirocco_clientimportClientfromscirocco_client.enumsimportTurbulenceModel,BoundaryType cli=Client("192.168.1.100",8080,"admin","123456")cli.login()proj=cli.get_project("PROJ_202606005")# 1. 入口边界：10m/s来流风proj.set_boundary(bound_name="inlet_west",bnd_type=BoundaryType.VELOCITY_INLET,params={"velocity":[10,0,0],"turb_intensity":0.05})# 2. 出口压力边界proj.set_boundary("outlet_east",BoundaryType.PRESSURE_OUTLET,params={"p_ref":0})# 3. 地面、建筑壁面proj.set_boundary("ground",BoundaryType.WALL,params={"roughness":0.3})proj.set_boundary("building_surface",BoundaryType.WALL,params={"roughness":0.02})# 4. 求解器配置：SST k-ω，最大3000步，残差1e-6收敛proj.set_solver_config(model_type=TurbulenceModel.SST_K_OMEGA,iter_num=3000,target_residual=1e-6)print("边界与求解器配置完成")cli.close()

案例4：提交仿真任务+阻塞等待仿真完成

fromscirocco_clientimportClient cli=Client("192.168.1.100",8080,"admin","123456")cli.login()proj=cli.get_project("PROJ_202606005")# 提交仿真任务，使用2块GPU，优先级2task=proj.submit_task(gpu_num=2,priority=2)print(f"任务ID：{task.task_id}，任务状态：{task.get_status()}")# 阻塞程序，直到仿真收敛/失败task.wait()# 判断仿真结果iftask.get_status()=="Converged":print("仿真收敛完成！")else:print("仿真异常终止，状态：",task.get_status())cli.close()

案例5：读取残差曲线+导出切面风速数据至CSV

fromscirocco_clientimportClientfromscirocco_clientimportResultReaderimportpandasaspd cli=Client("192.168.1.100",8080,"admin","123456")cli.login()proj=cli.get_project("PROJ_202606005")task=proj.get_last_task()# 初始化结果读取器res=ResultReader(proj,task_id=task.task_id)# 1. 获取残差曲线并保存residual_data=task.get_residual_curve()df_res=pd.DataFrame(residual_data)df_res.to_csv("./residual_log.csv",index=False)# 2. 截取Z=1.5m行人高度切面，导出风速、压力数据slice_data=res.extract_slice(plane="Z",pos=1.5,variables=["Ux","Uy","Uz","P","TurbKE"])df_slice=pd.DataFrame(slice_data)df_slice.to_csv("./pedestrian_wind_1.5m.csv",index=False)print("残差与行人高度切面数据导出完成")cli.close()

案例6：参数扫描批量仿真（正交DOE多风速工况）

批量遍历5m/s、8m/s、10m/s、12m/s四种来流风速自动仿真

fromscirocco_clientimportClientfromscirocco_client.enumsimportBoundaryType cli=Client("192.168.1.100",8080,"admin","123456")cli.login()base_proj_id="PROJ_202606006"wind_speed_list=[5,8,10,12]forwind_speedinwind_speed_list:# 复制基础工程生成工况工程new_proj=cli.copy_project(src_proj_id=base_proj_id,new_name=f"风速{wind_speed}m/s_工况仿真")# 修改入口风速边界new_proj.set_boundary("inlet_west",BoundaryType.VELOCITY_INLET,params={"velocity":[wind_speed,0,0]})# 提交任务并等待完成task=new_proj.submit_task(gpu_num=1)task.wait()# 导出每个工况行人高度数据res=ResultReader(new_proj,task.task_id)slice_df=pd.DataFrame(res.extract_slice("Z",1.5,["Ux","Uy"]))slice_df.to_csv(f"./wind_{wind_speed}_result.csv",index=False)print(f"{wind_speed}m/s工况仿真完成，数据已保存")cli.close()

案例7：查询服务算力+工程批量清理过期项目

fromscirocco_clientimportClientfromdatetimeimportdatetime,timedelta cli=Client("192.168.1.100",8080,"admin","123456")cli.login()# 1. 查询服务端算力资源resource_info=cli.health_check()print("服务端GPU总数：",resource_info["gpu_total"])print("空闲GPU：",resource_info["gpu_free"])print("内存占用率：",resource_info["mem_usage"])# 2. 筛选30天前创建的工程并批量删除cut_time=datetime.now()-timedelta(days=30)all_projs=cli.list_projects()del_count=0forpinall_projs:create_time=datetime.strptime(p.create_time,"%Y-%m-%d %H:%M:%S")ifcreate_time<cut_time:cli.delete_project(p.proj_id)del_count+=1print(f"批量清理过期工程共{del_count}个")cli.close()

案例8：仿真完成自动回调，自动生成可视化报告

使用回调函数监听任务状态，仿真结束自动拼接Excel汇总所有监控指标

fromscirocco_clientimportClient,SolverTaskimportpandasaspd cli=Client("192.168.1.100",8080,"admin","123456")cli.login()proj=cli.get_project("PROJ_202606008")# 定义仿真完成回调函数deftask_finish_callback(task:SolverTask):iftask.get_status()=="Converged":res=ResultReader(proj,task.task_id)# 获取全局监控系数cd=res.get_monitor_value("Cd")cl=res.get_monitor_value("Cl")max_wind=res.get_monitor_value("MaxWindSpeed")# 写入汇总表格report_df=pd.DataFrame([{"task_id":task.task_id,"drag_coeff":cd,"lift_coeff":cl,"max_wind_speed":max_wind}])report_df.to_excel("./sim_summary_report.xlsx",mode="a",index=False,header=False)print(f"任务{task.task_id}仿真完成，报告已更新")# 提交任务并绑定回调task=proj.submit_task()task.register_callback(task_finish_callback)task.wait()cli.close()

五、常见错误、报错原因与解决方案

1. ConnectionRefusedError 连接拒绝

报错：Connection refused on host:192.168.1.100 port 8080

• 原因：Scirocco服务端未启动、防火墙拦截端口、IP/端口填写错误
• 解决：登录服务器启动Scirocco后台服务；开放8080/50051端口；核对host与port参数

2. AuthFailedError 鉴权失败

报错：Invalid username/password or api_key

• 原因：账号密码错误、API密钥过期、账号无服务访问权限、token过期
• 解决：核对登录凭证；在Scirocco后台重新生成api_key；管理员分配工程权限；执行cli.login()重新刷新会话

3. GeometryUploadError 几何上传失败

报错：Geometry parse failed, unsupported file format

• 原因：几何文件损坏、非STL/STEP/IGS格式、模型尺寸异常、文件路径含中文
• 解决：导出纯净STEP模型；路径全部使用英文；缩小超大模型分块上传；检查模型无破损面片

4. MeshComputeError 网格划分崩溃

报错：Mesh generation terminated with error, negative volume detected

• 原因：几何重叠、网格尺寸差距过大、加密盒超出模型范围
• 解决：清理几何相交面；调大min_size_ratio；修正加密盒坐标范围

5. SolverTaskFailedError 仿真求解发散

报错：Solver diverged, residual explode

• 原因：网格质量极差、边界条件设置冲突、初始风速/压力梯度过大
• 解决：优化局部网格加密；降低入口流速；调松弛因子重新计算

6. TimeoutError 请求超时

报错：Request timeout after 30s

• 原因：服务端算力满载、大网格上传传输慢、网络延迟高
• 解决：Client初始化增大timeout参数；避开集群高峰期；分批次上传几何

7. ModuleNotFoundError: No module named ‘scirocco_client’

• 原因：未正确安装包、多Python环境混淆
• 解决：确认pip对应当前运行python；重新执行pip安装命令

8. ResultReadEmptyError 无仿真结果

报错：No result data found for task id

• 原因：仿真未收敛直接终止、任务中途手动删除、任务ID填写错误
• 解决：检查task状态是否Converged；核对task_id；重新运行仿真

六、使用注意事项与最佳实践

1. 连接与权限规范

1. 企业集群环境优先使用api_key鉴权，避免明文密码硬编码在代码中；可将密钥存入环境变量
2. 多工程循环仿真时，复用同一个Client对象，不要反复创建销毁连接，减少鉴权开销
3. 脚本结束必须调用cli.close()释放会话，避免服务端会话堆积占满连接池

2. 几何与网格优化

1. 几何文件路径禁止中文、空格、特殊符号，统一英文路径
2. 超大建筑模型拆分多块上传，单次文件不超过200MB，防止上传中断
3. 建筑近地面、外立面必须设置局部加密，行人高度网格尺寸≤0.5m保证精度

3. 仿真任务调度规范

1. GPU资源有限场景，增加任务判断逻辑，查询health_check空闲GPU数量再提交任务
2. 批量DOE仿真设置合理任务间隔，避免一次性提交上百任务堵塞队列
3. 长时间仿真使用register_callback异步监控，不使用无限阻塞wait()

4. 结果后处理存储规范

1. 大批量仿真结果分文件夹归档，按工程ID/任务ID分类命名CSV
2. 仅导出必要变量（Ux/Uy/P），减少VTK大文件存储，云端磁盘成本高
3. 定期通过脚本清理失败任务、过期网格文件，释放服务端存储空间

5. 兼容性限制

1. Python3.12不兼容，固定使用3.9/3.10稳定版本
2. Windows系统上传大文件易中断，大规模批量仿真推荐Linux服务器运行脚本
3. grpc协议仅支持内网高速集群，外网公网必须使用http/https协议

6. 异常容错建议

所有生产自动化脚本增加try-except捕获scirocco_client.exceptions下全部自定义异常，增加失败重试与日志输出，防止单工况报错中断整个批量仿真流程。

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。