Python之scirocco-pyclient包语法、参数和实际应用案例 scirocco-pyclient 完整使用手册一、包基础概述1. 软件定位与核心功能scirocco-pyclient是Scirocco 高性能流体/风环境仿真平台官方Python客户端SDK用于远程调用Scirocco仿真服务实现仿真任务全生命周期自动化无需手动打开Scirocco桌面客户端。Scirocco是专业CFD、城市风环境、建筑通风、光伏流场、热环境仿真软件该Python包是平台唯一官方编程交互接口。核心功能分类服务连接管理HTTP/HTTPS、内网RPC两种协议连接Scirocco服务端账号密钥鉴权、token会话缓存、多服务实例并行连接连接健康检测、断线自动重连、SSL证书校验开关工程项目操作创建、复制、重命名、删除仿真工程批量读取工程列表、筛选工程名称/创建时间/仿真类型工程配置文件.sci格式读写、参数批量修改网格模块自动化上传CAD几何模型STL/STEP/IGS至服务端远程启动网格划分、设置全局/局部网格加密尺寸查询网格进度、导出网格质量报告、下载网格文件仿真求解调度配置边界条件、湍流模型、求解步数、收敛判定标准提交串行/并行分布式仿真任务多GPU/多CPU集群任务启停、暂停、终止、优先级调整、队列管理结果数据读写与后处理实时获取监控曲线风速、压力、温度、阻力系数批量导出切面云图、等值面、流线数据CSV/VTK/TXT读取仿真残差、收敛日志、节点数据、单元场变量批量自动化与脚本扩展循环批量参数化仿真DOE正交试验、参数扫描本地文件批量上传、仿真结果自动归档回调函数绑定任务状态、仿真完成自动触发数据分析资源与权限管控查询服务端算力、内存、GPU占用工程权限分配、任务日志导出、操作审计记录2. 适用行业场景建筑风环境、城市微气候、光伏阵列流场、隧道通风、暖通CFD、汽车外流场、工业设备散热仿真自动化。二、完整安装教程环境依赖要求Python版本3.8 ~ 3.113.12存在兼容性bug官方暂不支持系统Windows10/Linux Ubuntu20.04/CentOS7/macOS12依赖库requests、numpy、pandas、pycryptodome、tqdm、vtk自动附带安装方式1PyPI标准安装推荐# 稳定正式版pipinstallscirocco-pyclient--upgrade# 指定国内镜像加速pipinstallscirocco-pyclient-ihttps://pypi.tuna.tsinghua.edu.cn/simple方式2离线源码安装内网无外网环境从Scirocco服务端安装目录获取源码包scirocco-pyclient.tar.gz解压后进入目录执行python setup.pyinstall方式3开发调试版本pipinstallscirocco-pyclientdev--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,# 服务端口默认8080RPC端口50051username:strNone,# 登录账号password:strNone,# 登录密码api_key:strNone,# 密钥鉴权企业集群推荐替代账号密码protocol:strhttp,# 协议http / https / grpcssl_verify:boolTrue,# 是否校验SSL证书内网测试可设Falsetimeout:int30,# 请求超时时间(秒)max_retry:int3,# 接口失败重试次数session_cache:boolTrue# 缓存登录token重复使用无需重新登录)Client 常用核心方法方法作用login()执行登录鉴权获取会话tokenlist_projects(filter: dict)查询全部工程支持名称、时间筛选create_project(name, sim_type)新建空白仿真工程get_project(proj_id)根据工程ID获取Project操作对象health_check()检测服务端连通性与算力状态close()关闭连接、销毁会话2. Project 工程操作类参数与语法获取工程对象clientClient(host192.168.1.100,port8080,usernameadmin,password123456)client.login()projclient.get_project(proj_idPROJ_202606001)核心方法参数upload_geometry(file_path, unitm)file_path本地几何文件路径STL/STEP/IGSunit几何单位 m/mm/cmset_mesh_global_size(base_size, min_size_ratio)base_size全局基础网格尺寸(float)min_size_ratio最小网格与基础网格比例(0~1)add_mesh_refinement(box_min, box_max, refine_size)局部加密盒box_min[x,y,z]、box_max[x,y,z]加密区域坐标set_boundary(bound_name, bnd_type, params: dict)bnd_type枚举VELOCITY、PRESSURE_INLET、PRESSURE_OUTLET、WALL、SYMMETRY等set_solver_config(model_type, iter_num, target_residual)model_typek-epsilon、k-omega SST、RNG k-epsilon等湍流模型iter_num最大迭代步数target_residual收敛残差阈值默认1e-6submit_task(gpu_num0, priority2)gpu_num使用GPU数量0仅CPUpriority1最高~5最低3. SolverTask 任务对象参数taskproj.submit_task()task.wait(timeoutNone)# 阻塞等待仿真完成task.stop()# 终止任务task.pause()# 暂停task.get_status()# 返回状态Pending/Running/Converged/Failedtask.get_residual_curve()# 获取残差数组4. ResultReader 后处理读取参数resResultReader(proj,task_idtask.task_id)# 导出切面数据datares.extract_slice(planeX,pos5.0,variables[Ux,Uy,Uz,P])# 导出云图文件res.export_contour(file_path./wind_slice.csv,planeZ,resolution200)# 获取全局监控值drag_coeffres.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. 初始化客户端并登录cliClient(host127.0.0.1,port8080,usernameadmin,passwordScirocco2026,protocolhttp)cli.login()print(服务连接成功服务状态,cli.health_check())# 2. 新建建筑风环境仿真工程new_projcli.create_project(name高层住宅风环境仿真,sim_typeSimType.WIND_ENVIRONMENT)print(新建工程ID,new_proj.proj_id)# 3. 关闭连接cli.close()案例2上传建筑STEP几何全局网格设置fromscirocco_clientimportClient cliClient(192.168.1.100,8080,admin,123456)cli.login()projcli.create_project(商业综合体通风,sim_typeWIND_ENVIRONMENT)# 上传本地STEP建筑模型proj.upload_geometry(file_pathr./building.step,unitm)# 设置全局网格基础尺寸2m最小网格比例0.1proj.set_mesh_global_size(base_size2.0,min_size_ratio0.1)# 增加近建筑局部加密加密尺寸0.5mproj.add_mesh_refinement(box_min[-50,-50,0],box_max[80,80,120],refine_size0.5)print(几何上传网格配置完成)cli.close()案例3批量设置边界条件配置SST湍流求解器fromscirocco_clientimportClientfromscirocco_client.enumsimportTurbulenceModel,BoundaryType cliClient(192.168.1.100,8080,admin,123456)cli.login()projcli.get_project(PROJ_202606005)# 1. 入口边界10m/s来流风proj.set_boundary(bound_nameinlet_west,bnd_typeBoundaryType.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_typeTurbulenceModel.SST_K_OMEGA,iter_num3000,target_residual1e-6)print(边界与求解器配置完成)cli.close()案例4提交仿真任务阻塞等待仿真完成fromscirocco_clientimportClient cliClient(192.168.1.100,8080,admin,123456)cli.login()projcli.get_project(PROJ_202606005)# 提交仿真任务使用2块GPU优先级2taskproj.submit_task(gpu_num2,priority2)print(f任务ID{task.task_id}任务状态{task.get_status()})# 阻塞程序直到仿真收敛/失败task.wait()# 判断仿真结果iftask.get_status()Converged:print(仿真收敛完成)else:print(仿真异常终止状态,task.get_status())cli.close()案例5读取残差曲线导出切面风速数据至CSVfromscirocco_clientimportClientfromscirocco_clientimportResultReaderimportpandasaspd cliClient(192.168.1.100,8080,admin,123456)cli.login()projcli.get_project(PROJ_202606005)taskproj.get_last_task()# 初始化结果读取器resResultReader(proj,task_idtask.task_id)# 1. 获取残差曲线并保存residual_datatask.get_residual_curve()df_respd.DataFrame(residual_data)df_res.to_csv(./residual_log.csv,indexFalse)# 2. 截取Z1.5m行人高度切面导出风速、压力数据slice_datares.extract_slice(planeZ,pos1.5,variables[Ux,Uy,Uz,P,TurbKE])df_slicepd.DataFrame(slice_data)df_slice.to_csv(./pedestrian_wind_1.5m.csv,indexFalse)print(残差与行人高度切面数据导出完成)cli.close()案例6参数扫描批量仿真正交DOE多风速工况批量遍历5m/s、8m/s、10m/s、12m/s四种来流风速自动仿真fromscirocco_clientimportClientfromscirocco_client.enumsimportBoundaryType cliClient(192.168.1.100,8080,admin,123456)cli.login()base_proj_idPROJ_202606006wind_speed_list[5,8,10,12]forwind_speedinwind_speed_list:# 复制基础工程生成工况工程new_projcli.copy_project(src_proj_idbase_proj_id,new_namef风速{wind_speed}m/s_工况仿真)# 修改入口风速边界new_proj.set_boundary(inlet_west,BoundaryType.VELOCITY_INLET,params{velocity:[wind_speed,0,0]})# 提交任务并等待完成tasknew_proj.submit_task(gpu_num1)task.wait()# 导出每个工况行人高度数据resResultReader(new_proj,task.task_id)slice_dfpd.DataFrame(res.extract_slice(Z,1.5,[Ux,Uy]))slice_df.to_csv(f./wind_{wind_speed}_result.csv,indexFalse)print(f{wind_speed}m/s工况仿真完成数据已保存)cli.close()案例7查询服务算力工程批量清理过期项目fromscirocco_clientimportClientfromdatetimeimportdatetime,timedelta cliClient(192.168.1.100,8080,admin,123456)cli.login()# 1. 查询服务端算力资源resource_infocli.health_check()print(服务端GPU总数,resource_info[gpu_total])print(空闲GPU,resource_info[gpu_free])print(内存占用率,resource_info[mem_usage])# 2. 筛选30天前创建的工程并批量删除cut_timedatetime.now()-timedelta(days30)all_projscli.list_projects()del_count0forpinall_projs:create_timedatetime.strptime(p.create_time,%Y-%m-%d %H:%M:%S)ifcreate_timecut_time:cli.delete_project(p.proj_id)del_count1print(f批量清理过期工程共{del_count}个)cli.close()案例8仿真完成自动回调自动生成可视化报告使用回调函数监听任务状态仿真结束自动拼接Excel汇总所有监控指标fromscirocco_clientimportClient,SolverTaskimportpandasaspd cliClient(192.168.1.100,8080,admin,123456)cli.login()projcli.get_project(PROJ_202606008)# 定义仿真完成回调函数deftask_finish_callback(task:SolverTask):iftask.get_status()Converged:resResultReader(proj,task.task_id)# 获取全局监控系数cdres.get_monitor_value(Cd)clres.get_monitor_value(Cl)max_windres.get_monitor_value(MaxWindSpeed)# 写入汇总表格report_dfpd.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,modea,indexFalse,headerFalse)print(f任务{task.task_id}仿真完成报告已更新)# 提交任务并绑定回调taskproj.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. 连接与权限规范企业集群环境优先使用api_key鉴权避免明文密码硬编码在代码中可将密钥存入环境变量多工程循环仿真时复用同一个Client对象不要反复创建销毁连接减少鉴权开销脚本结束必须调用cli.close()释放会话避免服务端会话堆积占满连接池2. 几何与网格优化几何文件路径禁止中文、空格、特殊符号统一英文路径超大建筑模型拆分多块上传单次文件不超过200MB防止上传中断建筑近地面、外立面必须设置局部加密行人高度网格尺寸≤0.5m保证精度3. 仿真任务调度规范GPU资源有限场景增加任务判断逻辑查询health_check空闲GPU数量再提交任务批量DOE仿真设置合理任务间隔避免一次性提交上百任务堵塞队列长时间仿真使用register_callback异步监控不使用无限阻塞wait()4. 结果后处理存储规范大批量仿真结果分文件夹归档按工程ID/任务ID分类命名CSV仅导出必要变量Ux/Uy/P减少VTK大文件存储云端磁盘成本高定期通过脚本清理失败任务、过期网格文件释放服务端存储空间5. 兼容性限制Python3.12不兼容固定使用3.9/3.10稳定版本Windows系统上传大文件易中断大规模批量仿真推荐Linux服务器运行脚本grpc协议仅支持内网高速集群外网公网必须使用http/https协议6. 异常容错建议所有生产自动化脚本增加try-except捕获scirocco_client.exceptions下全部自定义异常增加失败重试与日志输出防止单工况报错中断整个批量仿真流程。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。