マニュアル

cutmesh は、水密な STL の内部に八分木ベースの多面体メッシュを作り、OpenFOAM の constant/polyMesh を直接書き出すメッシャーです。八分木のセルを STL で直接切断(カットセル)して壁面を作ります。 設定はすべて 1 つの JSON ファイル(meshDict.json)に書きます。

開発中のプロトタイプです。メッシュ品質は checkMesh と同じ式の自前チェックで確認していますが、OpenFOAM 本体での検証は限られています。 使う前に手元で checkMesh を実行してください。

インストール

必要なもの: Python 3.9 以上、numpy、scipy(断面図を描くなら matplotlib)。メッシュ生成に OpenFOAM は要りません。

git clone https://github.com/mmer547/cutmesh.git
cd cutmesh
pip install -e .                      # オフライン環境では --no-build-isolation(要 wheel)
python tools/build_rust.py            # 任意: Rust 拡張のビルド(約 4 倍速くなる)

インストールしない場合は、リポジトリの直下から python -m cutmesh で実行するか、PYTHONPATH にリポジトリのディレクトリを通してください。

使い方

cutmesh meshDict.json [-case DIR] [-noCheck]    # python -m cutmesh でも同じ
オプション意味
-case DIR出力先のケースディレクトリ(meshDict の case より優先)
-noCheck生成後の品質チェックを省く(大きなメッシュで約 1 割速くなる)

最小限の meshDict.json(STL の内部だけのメッシュ):

{
  "domain": "model.stl",
  "baseCellSize": 0.01,
  "surfaceRefinement": { "default": 2 },
  "patchTypes": { "inlet": "patch", "outlet": "patch" },
  "case": "case"
}

case/constant/polyMesh が書き出され、続けて品質チェックの結果がログに出ます。パス(domain など)は meshDict.json のあるディレクトリからの相対パスです。STL の solid 名がそのままパッチ名になり、patchTypes に書かないパッチは wall になります。

ログの見方:

攪拌槽の例題は examples/stirred_tank にあります。画像つきの説明は 実行例 を見てください。

cd examples/stirred_tank
python make_geometry.py               # サンプル STL を生成
cutmesh meshDict.json                 # → case/constant/polyMesh, case/constant/MRFProperties
python run.py                         # 断面図も欲しい場合 → slice_z.png, slice_y.png

meshDict.json

_ または // で始まるキーはコメントとして無視されます。知らないキーは警告されます(綴りの誤りで設定が黙って無視されないように)。

フォームで作ることもできます: meshDict 作成(STL の solid 名と大きさを読み、入力をその場で検査します)。エディターの補完には JSON Schema が使えます。

基本

キー意味既定値
domain流体領域の STL(閉曲面、複数 solid 可。solid 名がパッチ名)。ASCII・バイナリどちらも可必須
baseCellSizeレベル 0 のセルの辺長 [m]。レベル L のセルは baseCellSize / 2^L必須
case出力先のケースディレクトリ.
patchTypesパッチ名 → タイプ(wall, patch など)すべて wall
paddingSTL の外接箱の周りに足すベースセルの数1
rotatingZones回転ゾーンのリスト(回転ゾーン)[]
baseMeshベースメッシュ(円筒ベースメッシュ)直交格子
addLayers境界層の設定(境界層)なし

細分化

キー意味既定値
surfaceRefinementsolid 名 → 細分化レベル。default で既定値{}
featureLevel特徴線(鋭角エッジ)の近くの細分化レベル(null = 表面の最大レベル)null
featureAngle特徴線を抽出する角度 [deg]30
refinementRegions体積の細分化領域 [{"cylinder": {...}, "level": n}][]
bufferLayersレベルの遷移ごとのバッファセルの数。1 にするとセル数が減る2
gapRefinement{"thickness": t, "level": L}: 流体の厚みが t 未満の所(スロットの先端、狭い流路)の壁を L まで細分化なし
autoGapRefinement{"cellsAcross": n, "maxLevel": L}(true で既定値): 壁から法線方向に向かいの壁までの隙間の幅 w を測り、隙間に n 個のセルが入るレベル(上限 L)まで壁を細分化する。厚さを指定せずに、溝・スリット・狭い隙間がつぶれるのを防ぐn = 3、L = 表面レベルの最大 + 2

スナップと統合

キー意味既定値
snapTolerance節点を表面へ寄せる距離(セル辺長比)。スライバーセルを防ぐ0.3
featureSnapTolerance特徴線(STL の鋭角エッジ・円筒の縁)へ寄せる距離(セル辺長比)0.5
featureSnapMax実験的: この距離まで特徴線へ寄せ、八分木セルが壊れる所だけ取り消す。一部のカットセルが反転するため既定では無効0.5
concaveSnapMax凹の鋭角エッジでは、固体側の節点をこの距離までエッジ上へ寄せる0.75
hangingSnap表面へ届かないぶら下がり節点の扱い("free": 表面へ直接投影、"constrained": 動かさない)"free"
featureCaps凸の鋭角部でカット面を特徴線に沿わせる("domain" / "zone" / "both" / false)"domain"
exactFeatureCut凸の鋭角エッジの近くのセルを、STL の平面で直接切る。格子に沿わないエッジがギザギザにならない(featureCaps が "domain" か "both" のときだけ働く)true
mergeRatio元の六面体の体積比でこれ未満のカットセルを隣のセルに統合する0.25
mergeMaxNonOrtho統合後の非直交角の上限 [deg]65
mergeWallFaces1 つのセルの、ほぼ同一平面の壁面の断片を 1 つの面にまとめるtrue

薄い形状

キー意味既定値
fillThinGaps中に流体があるのに角の頂点がどれも流体にないセル(格子の面の間を通る薄い隙間)を分割する回数。0 で無効(直交格子のみ)2
fillThinWalls中に固体の薄い壁があるのに角の頂点がどれも固体にないセルを分割する回数。壁が消えて両側の流体がつながるのを防ぐ(直交格子のみ)3
thinCutCells壁で切られて流体が少ししか残らず、隣に細かいセルがあるセルを分割する回数(直交格子のみ)2
thinCutFractionthinCutCells の対象にする流体の割合0.35
minRegionVolume流体の本体とつながっていない領域のうち、体積が全体のこの割合未満のものを削除する(それ以上は警告)1e-3

検査と出力

キー意味既定値
checkLeaks流体が固体の壁を越えてつながっていないかを検査し、見つかれば場所をログに出すtrue
strictInputSTL に開いた辺・非多様体の辺があるとき、警告ではなくエラーで止めるfalse
volumeCheckToleranceメッシュの体積と STL の体積の差がこの割合を超えたら警告する0.05
writeFormatpolyMesh の形式: "binary" または "ascii"(書き出し形式)"binary"
writeMRFProperties回転ゾーンがあるとき constant/MRFProperties の雛形を書く("ami": true のゾーンは除く)true
openfoamスライディングメッシュの書き方: "com"(openfoam.com / ESI)、"org10"・"org11"・"org12"(openfoam.org)(スライディングメッシュ)"com"
writeDynamicMeshDict"ami": true のゾーンがあるとき constant/dynamicMeshDict を書くtrue
amiExactRims"ami": true のゾーンの界面を、ゾーンの縁(円筒の上下の縁)にぴったり沿わせる(縁の外側のセルを 2 つに切る)(スライディングメッシュ)true

回転ゾーン(rotatingZones)

MRF やスライディングメッシュ(AMI)用の回転領域を円筒で指定します。円筒は八分木のカットで切断されるので、 円筒面そのものがメッシュの内部面になります(生成後にセル中心でゾーンを選ぶ方式ではありません)。 界面は粗いセルでも厳密に円筒面上にあるので、界面のために細分化する必要がありません。

"rotatingZones": [
  { "name": "rotor",
    "cylinder": { "point1": [0, 0, 0.06], "point2": [0, 0, 0.14], "radius": 0.07 },
    "surfaceLevel": 2, "volumeLevel": 2, "omega": 31.416, "nonRotatingPatches": [] }
]
キー意味
nameゾーン名(cellZone 名、faceZone は <name>_interface)
cylinder円筒: 軸の両端 point1・point2 と半径 radius
stl, origin, axis円筒の代わりに閉じた STL で与える(examples/stirred_tank/meshDict_stlRotor.json)
surfaceLevel / volumeLevelゾーンの面 / 内部の細分化レベル
omega角速度 [rad/s](MRFProperties に書く)
nonRotatingPatchesゾーン内でも回転させないパッチ
wallProximity{"distance": d, "level": L}: ゾーンの面のうち STL から d 以内の部分だけを L まで細分化する。界面を壁すれすれに置く(狭い隙間の中に置く)場合に、ゾーン面全体を細かくせずに済む
amitrue にすると、界面をスライディングメッシュ用の 2 つのパッチに分け、dynamicMeshDict を書く(スライディングメッシュ)
conformingfalse にすると界面をメッシュに沿わせず、セル中心が円筒内にあるセルを cellZone にする(MRF 用。AMI には使えない)。界面が狭い隙間の中にあって沿わせられない場合に使う

出力: cellZones(回転領域)、faceZones(<name>_interface: 円筒界面、向きつき)、 constant/MRFProperties の雛形。複数のゾーンを置けます(重ならないこと)。

狭い隙間の中に界面を置く場合(ローター・ステーターなど): 界面と両側の壁の間にそれぞれ 1 セル以上入るよう、 wallProximity の level を「隙間の半分 ≧ セル寸法」になるように選びます。隙間が狭いほどセル数が急に増えます (実行例: ローター・ステーター)。

スライディングメッシュ(AMI)

回転ゾーンに "ami": true を付けると、界面の内部面を、回転側のセルが持つ面と静止側のセルが持つ面の 2 つのパッチに分け、 界面の点を回転側だけ複製して切り離します(OpenFOAM の createBaffles と mergeOrSplitBaffles -split / splitBaffles をまとめて行うのと同じ)。 境界層は分ける前に付けます。あわせて constant/dynamicMeshDict(cellZone の剛体回転)を書きます。このゾーンは MRFProperties には書きません。

"rotatingZones": [
  { "name": "rotor",
    "cylinder": { "point1": [0, 0, 0.06], "point2": [0, 0, 0.14], "radius": 0.07 },
    "surfaceLevel": 2, "volumeLevel": 2, "omega": 31.416,
    "ami": true }
],
"openfoam": "com"

書き方は OpenFOAM の配布元によって違うので、openfoam で選びます。

openfoamパッチ(回転側 / 静止側)dynamicMeshDictOpenFOAM での手順
"com"(既定)<name>_AMI1 / <name>_AMI2、型 cyclicAMIdynamicMotionSolverFvMesh + solidBodyそのまま使える
"org10"・"org11"・"org12"<name>_nonCouple1 / <name>_nonCouple2、型 patchmover { type motionSolver; ... }createNonConformalCouples -overwrite <name>_nonCouple1 <name>_nonCouple2 でつなぐ

書き方は各配布元のチュートリアル(openfoam.com: interFoam/RAS/mixerVesselAMI、openfoam.org 10〜12: mixerVessel2D)に合わせています。 examples/stirred_tank/meshDict_ami.json(約 10 万セル、層流で 90° 回転)で、openfoam.com v2606 の pimpleFoam と OpenFOAM-13 の foamRun("org12" の書き方のまま)は最後まで回ることを確かめました。 OpenFOAM-12 では、このメッシュでも縁のない円筒ゾーンでも、回し始めると cyclicFvPatch::makeWeights の浮動小数点例外で止まりました(同じメッシュが OpenFOAM-13 では回るので、OpenFOAM-12 側の問題とみています)。

円筒ベースメッシュ(baseMesh)

回転機械向けに、八分木の根を直交格子の代わりに軸まわりの同心ブロックにできます。 ブロックの配置(中心の正方形・リングの半径・分割数)は自動で決まるので、最小限の指定は次だけです。

"baseMesh": { "type": "cylindrical", "origin": [0, 0, 0], "axis": [0, 0, 1] }
キー意味既定値
origin, axis回転軸(原点と方向)[0,0,0], [0,0,1]
zRange軸方向の範囲 [z0, z1](origin からの距離)STL の範囲 ± baseCellSize
nz / dz軸方向の分割数 / 幅(全ブロック共通)dz = baseCellSize
rOuter最外ブロックの外半径(自動配置)STL の半径 + 2/3 × cellSize
cellSize自動配置の目標寸法(半径方向・周方向のセル幅)baseCellSize と dz の小さい方
core, blocksブロックを手で指定する場合(下記)。両方書くか、両方書かない自動配置
maxSizeRatioブロック境界をまたぐセル寸法の比の上限2.5

自動配置(core と blocks を書かない場合)

手動指定

"core": { "halfWidth": 0.0375, "n": 6 },
"blocks": [
  { "rOuter": 0.06, "nr": 2 },
  { "rOuter": 0.10, "nr": 3, "nTheta": 38 },
  { "rOuter": 0.155, "nr": 4 }
]

共通

境界層(addLayers)

壁パッチにプリズム層を追加します。meshDict に書くと生成後に自動で追加され、既存のメッシュに後から追加することもできます (cutmesh 以外で作った polyMesh でも可)。

# meshDict.json に "addLayers": {...} を書く(例: examples/stirred_tank/meshDict_layers.json)
cutmesh examples/stirred_tank/meshDict_layers.json
# 既存のケースに追加
python -m cutmesh.layers CASE [layerDict.json] [-out CASE2] [-noCheck] [-ascii | -binary]
キー意味既定値
patches層を付けるパッチ名のリストtype が wall の全パッチ
nLayers層の数3
expansionRatio壁から内側への層厚の比1.2
finalLayerThickness最も内側の層の厚さ(relativeSizes なら局所セル寸法比)0.3
relativeSizes厚さを局所セル寸法に対する比で与えるtrue
minThickness総厚がこれ未満の所は層を付けない0.05
maxNonOrtho非直交角 [deg] がこれを超えるセルは不正とみなし、そこで層を薄くする65
maxSkewness歪度がこれを超える面のセルは不正とみなす(null で無効)4
maxGapFraction総厚を、向かい合う壁までの距離のこの割合以下に抑える(0 で無効)0.3
maxThicknessSlope壁に沿った総厚の変化の上限(層の端を徐々に細らせる)0.5

このほか minNormalCos, wallNonOrthMargin, cornerStretch, mergeWallPoints, concaveSlide, nRings, nSmooth, nIter, nCollapseIter があります(README の「境界層」)。 "addLayers": {} は既定値で層を追加します。狭い隙間がある形状では finalLayerThickness を 0.15 程度にすると、 目標の厚さに達する節点が大きく増えます。ログに、目標の厚さに達した壁節点・薄くなった節点・層なしの節点の割合が出ます。

書き出し形式(writeFormat)

polyMesh は既定でバイナリ(OpenFOAM の writeFormat binary と同じ形式)で書き出します。 大きなファイル(points・faces・owner・neighbour)がバイナリになり、 boundary・cellZones・faceZones は ASCII のままです。中身を目で確かめたいときや、 ASCII しか読めないツールに渡すときは "writeFormat": "ascii" にします。

約 69 万セルASCIIバイナリ
書き出し4.3〜4.5 秒0.14〜0.19 秒
ファイルの大きさ122 MB80 MB
読み込み(cutmesh)3.1 秒0.18 秒

バイナリの形式は OpenFOAM のソースに合わせて書いていますが、OpenFOAM 本体で読めることはまだ確認していません。読めない場合は "writeFormat": "ascii" にするか、OpenFOAM の foamFormatConvert で変換してください。

高速化(Rust 拡張)

最近点・内外判定・符号付き距離、回転ゾーンのカット、面とセルの重心と体積、境界層の平滑化などを Rust(BVH + rayon による並列化)で計算します。 Rust ツールチェーン(cargo)があれば次でビルドされ、cutmesh/_core が置かれます。無ければ Python/NumPy の処理で動きます(結果は同じ)。

python tools/build_rust.py                          # cargo build --release + パッケージへコピー
CUTMESH_NO_RUST=1 python -m cutmesh meshDict.json   # Python の処理を強制(比較用)
例題PythonRust 拡張あり
examples/stirred_tank26 秒7 秒
別の実形状(55 万セル)162 秒41 秒
同、境界層の追加(3 層)51 秒27 秒

設定と入力の検査

メッシュを作り始める前に meshDict.json を検査します。

入力 STL の自動修正: cutmesh が入力を直したときは、必ずログに REPAIR: で始まる行を出します。黙って直すことはしません。

修正理由
面積 0 の三角形を除く法線が決まらず、特徴線や交点の計算を乱す
重複した三角形は 1 枚だけ残す内外判定(光線の交差回数の偶奇)で交差が 2 回数えられ、内外が反転する
重なった逆向きの三角形の対(厚さ 0 の膜)は 2 枚とも除く同上
REPAIR: domain STL: removed 20 zero-area triangles, 50 duplicated triangles (one copy kept) (1350 -> 1280 triangles)

直さずに WARNING: を出すもの: 開いた辺、非多様体の辺、向きの食い違う辺。問題がなければ domain STL check: closed, consistently oriented, N triangles と出ます。メッシュの完成後には、メッシュの体積を STL の体積と比べます (volume check: mesh ..., STL ... (+x%))。

コマンドとオプション

パスはリポジトリの直下から実行する場合のものです。pip install -e . をすれば cutmesh と python -m cutmesh.* はどこからでも使えます。

メッシュの生成: cutmesh

cutmesh meshDict.json [-case DIR] [-noCheck]      # python -m cutmesh でも同じ
オプション意味
-case DIR出力先のケースディレクトリ(meshDict の case より優先)
-noCheck生成後の品質チェックを省く
-h, --help使い方を表示する

終了コード: 0 = 成功、1 = 設定や STL のエラー(ERROR: ... と表示)、2 = 引数の誤り。

境界層の追加: python -m cutmesh.layers

python -m cutmesh.layers CASE [layerDict.json] [-out CASE2] [-noCheck] [-ascii | -binary]
引数・オプション意味
CASE層を付けるメッシュのケース(CASE/constant/polyMesh)
layerDict.json層の設定(境界層の表のキー)。meshDict を渡すと、その addLayers を使う。省略すると既定値
-out CASE2書き出し先(省略すると CASE を上書き)
-noCheck品質チェックを省く
-ascii / -binary書き出し形式(省略すると入力と同じ)

スライディングメッシュへの変換: python -m cutmesh.ami

python -m cutmesh.ami CASE [-zone NAME ...] [-openfoam com|org10|org11|org12] [-out CASE2] [-noDynamicMeshDict] [-ascii | -binary]
引数・オプション意味
CASEcellZone NAME と faceZone NAME_interface を持つメッシュ(cutmesh が書いたもの)
-zone NAME変換するゾーン(複数回指定できる。省略すると、faceZone の対があるゾーンすべて)
-openfoam書き方(既定 com)
-out CASE2書き出し先(省略すると CASE を上書き)
-noDynamicMeshDictdynamicMeshDict を書かない(回転の設定は constant/MRFProperties から読む。変換したゾーンの項目は MRFProperties から取り除く)
-ascii / -binary書き出し形式(省略すると入力と同じ)

メッシュの確認

コマンド内容
python -m cutmesh.diagnose meshDict.json [CASE]流体が固体の壁を越えてつながっていないかを調べる(checkLeaks と同じ検査)。CASE を省くと meshDict の case。見つかれば終了コード 1
python tools/edge_check.py meshDict.json [-case DIR]STL の特徴線と円筒ゾーンの縁に沿って、最寄りのメッシュの辺までの距離を最小セル寸法比で表示する(捉えられていれば 0)。メッシュを作り直して測る。-case を付けるとそのメッシュも書き出す
python benchmark/render_mesh.py CASE [-o OUT] [--title NAME]3D 図(overview.png: 壁面、cut.png: 内部の切り口と 3 断面)を描く。品質の悪いセルは赤。-o の既定は CASE の親ディレクトリ
python benchmark/stl_check.py model.stl [...] [--json]入力 STL の診断(開いた辺、非多様体の辺、向きの不一致、重複・面積 0 の三角形、部品の数、体積)

ベンチマーク: benchmark/run_bench.py

多数の STL をまとめて通し、判定(PASS / WARN / INVALID / ERROR)・セル数・品質・時間を一覧にします。1 ケースずつ別のプロセスで動くので、落ちても他のケースは続きます。

python benchmark/make_synthetic.py                           # 人工形状の STL を生成(初回だけ)
python benchmark/run_bench.py benchmark/suites/synthetic.json [オプション]
オプション意味
-j NN ケースを並列に走らせる(時間を比べるときは 1 にする)
--only PATTERNケース名で絞る(ワイルドカード可。複数回指定できる)
--cells-across N全ケースのベースセルを「外接箱の最長辺 / N」にする(既定 24)
--set KEY=JSON全ケースの meshDict のキーを上書きする(例: --set addLayers='{"nLayers": 3}')
--keep合格したケースの polyMesh も残す(既定では消す)
--no-images画像を描かない
--out DIR出力先(既定 benchmark/results/<スイート>-<日時>)
--baseline FILE過去の結果と比べ、悪化があれば終了コード 1
--save-baseline結果を benchmark/baselines/<スイート>.json に保存する
--timeout SEC1 ケースの時間の上限(既定 900 秒)
--vol-tol X体積の差がこの割合を超えたら WARN(既定 0.01)
--strictcheckMesh より厳しい判定(面の三角形分割の四面体)も WARN に数える

スイート: synthetic.json(人工形状 26 個)、large.json(約 100 万セル・回転ゾーンなど、速さの確認用)、local.json(手元の実形状)。詳しくは benchmark/README.md。

そのほか

コマンド内容
python tools/build_rust.py [--debug]Rust 拡張をビルドしてパッケージに置く(cargo が必要)
python examples/stirred_tank/make_geometry.py [--stator GAP_MM]攪拌槽の STL を生成する。--stator で翼の外側に隙間 GAP_MM の固定リングを付ける
python examples/stirred_tank/run.py [meshDict]例題のメッシュを作って断面図(slice_z.png, slice_y.png)を描く
python tools/make_docs_images.py [--only NAME ...]このサイトの画像を作り直す
CUTMESH_NO_RUST=1環境変数。Rust 拡張があっても Python の処理を使う(比較用)

既知の制約