classy_blocks

Python classes for easier creation of OpenFOAM's blockMesh dictionaries.

Warning! This project is currently under development and is not yet very user-friendly. It still lacks some important features and probably features a lot of bugs. However, you're welcome to suggest features, improvements, and point out bugs.

About

blockMesh is a very powerful mesher but the amount of manual labour it requires to make even the simplest meshes makes it mostly useless. Even attempts to simplify or parametrize _blockMeshDict_s with #calc or even the dreadful m4 quickly become unmanageable and cryptic.

classy_blocks' aim is to ease the burden of meticulous work by providing a more intuitive workflow, off-the-shelf parts and some automatic helpers for building and optimization of block-structured hexahedral meshes. Still it is not an automatic mesher and therefore some kinds of geometry are more suited than others.

Useful For

Fields

Turbomachinery (impellers, propellers)
Microfluidics
Flow around buildings
Heat transfer (PCB models, heatsinks)
Airfoils (2D)
Solids (heat transfer, mechanical stresses)

Cases

Simpler rotational geometry (immersed rotors, mixers)
Pipes/channels
Tanks/plenums/containers
External aerodynamics of blunt bodies
Modeling thin geometry (seals, labyrinths)
Parametric studies
Background meshes for snappy (cylindrical, custom)
2D and axisymmetric cases
Overset meshes

Not Good For

External aerodynamics of vehicles (too complex to mesh manually, without refinement generates too many cells)
Complex geometry in general
One-off simulations (use automatic meshers)

How To Use It

If you just need the classy_blocks, install them with: pip install git+https://github.com/damogranlabs/classy_blocks.git
If you want to run examples, follow instructions in EXAMPLES_README.md
If you want to contribute, follow instructions in CONTRIBUTING.md

Features

Workflow

As opposed to blockMesh, where the user is expected to manually enter pre-calculated vertices, edges, blocks and whatnot, classy_blocks tries to mimic procedural modeling of modern 3D CAD programs. Here, a Python script contains steps that describe geometry of blocks, their cell count, grading, patches and so on. At the end, the procedure is translated directly to blockMeshDict and no manual editing of the latter should be required.

Building Elements

Unchecked items are not implemented yet

Modifiers

After blocks have been placed, it is possible to create new geometry based on placed blocks or to modify them.

Move Block's Vertex/Edge/Face
Delete a Block created by a Shape or Object
Project Block's Vertex/Edge/Face*
Chain Block's face to generate a new block
Chain Shape's surface (top/bottom/outer) to generate a new Shape
Join two Blocks by extending their Edges
Offset Block's faces to form new Blocks for easier creation of layouts with boundary layers that don't propagate into domain
Optimize Vertex positions

Meshing specification

Simple definition of edges: a single point for circular, a list of points for a spline edge, name of geometry for projecting
Automatic calculation of cell count and grading by specifying any of a number of parameters (cell-to-cell expansionr atio, start cell width, end cell width, total expansion ratio)
Edge grading (separate specification for each edge)
Automatic propagation of grading and cell count from a single block to all connected blocks as required by blockMesh
Projections of vertices, edges and block faces to geometry (triangulated and searchable surfaces)*
Face merging as described by blockMesh user guide. Breaks the pure-hexahedral-mesh rule but can often save the day for trickier geometries.

Not implemented: projected Vertex

Examples

Shapes

A simple Cylinder:

inlet = Cylinder([x_start, 0, 0], [x_end, 0, 0], [0, 0, radius])
inlet.chop_radial(count=n_cells_radial, end_size=boundary_layer_thickness)
inlet.chop_axial(start_size=axial_cell_size, end_size=2*axial_cell_size)
inlet.chop_tangential(count=n_cells_tangential)

inlet.set_bottom_patch('inlet')
inlet.set_outer_patch('wall')
inlet.set_top_patch('outlet')
mesh.add(inlet)

See examples/shape for use of each shape and examples/complex for a more real-life example usage of shapes.

Operations

Analogous to a sketch in 3D CAD software, a Face is a set of 4 vertices and 4 edges. An Operation is a 3D shape obtained by swiping a Face into 3rd dimension by a specified rule; an example of Revolve:

# a quadrangle with one curved side
base = Face(
    [ # quad vertices
        [0, 0, 0],
        [1, 0, 0],
        [1, 1, 0],
        [0, 1, 0]
    ],
    [ # edges: None specifies straight edge
        [0.5, -0.2, 0], # single point: arc
        None,
        None,
        None
  ]
)

revolve = Revolve(
    base, # face to revolve
    f.deg2rad(45), # revolve angle
    [0, -1, 0], # axis
    [-2, 0, 0]  # origin
)

revolve.chop(0, count=15) # first edge
revolve.chop(1, count=15) # second edge
revolve.chop(2, start_size=0.05) # revolve direction
mesh.add(revolve)

See examples/operations for an example of each operation.

Projection To Geometry

Any geometry that snappyHexMesh understands is also supported by blockMesh. That includes searchable surfaces such as spheres and cylinders and triangulated surfaces. Simply provide geometry definition as documentation specifies, then call a project_face() on Block object.

geometry = {
    'terrain': [
        'type triSurfaceMesh',
        'name terrain',
        'file "terrain.stl"',
    ]
}

base = Face([
    [-1, -1, -1],
    [ 1, -1, -1],
    [ 1,  1, -1],
    [-1,  1, -1]
])

extrude = Extrude(base, [0, 0, 2])
extrude.block.project_face('bottom', 'terrain', edges=True)
extrude.chop(0, count=20)
extrude.chop(1, count=20)
extrude.chop(2, start_size=0.01, c2c_expansion=1.2)

extrude.set_patch('bottom', 'terrain')
mesh.add(extrude)
mesh.set_default_patch('atmosphere', 'patch')

Face Merging

Simply provide names of patches to be merged and call mesh.merge_patches(<master>, <slave>). classy_blocks will take care of point duplication and whatnot.

box = Box([-0.5, -0.5, 0], [0.5, 0.5, 1])
for i in range(3):
    box.chop(i, count=25)
box.set_patch('top', 'box_top')
mesh.add(box)

cylinder = Cylinder(
    [0, 0, 1],
    [0, 0, 2],
    [0.25, 0, 1]
)
cylinder.chop_axial(count=10)
cylinder.chop_radial(count=10)
cylinder.chop_tangential(count=20)

cylinder.set_bottom_patch('cylinder_bottom')
mesh.add(cylinder)

mesh.merge_patches('box_top', 'cylinder_bottom')

Chaining and expanding/contracting

Useful for Shapes, mostly for piping and rotational geometry; An existing Shape's start or end sketch can be reused as a starting sketch for a new Shape, as long as they are compatible. For instance, an Elbow can be chained to a Cylinder just like joining pipes in plumbing.

Moreover, most shapes* can be expanded to form a wall version of the same shape. For instance, expanding a Cylinder creates an ExtrudedRing.

See examples/chaining for an example of each operation.

Debugging

By default, a debug.vtk file is created where each block represents a hexahedral cell. By showing block_ids with a proper color scale the blocking can be visualized. This is useful when blockMesh fails with errors reporting invalid/inside-out blocks but VTK will happily show anything.

Prerequisites

Package (python) dependencies can be found in setup.py file. Other dependencies that must be installed:

blockMesh (OpenFOAM)
OpenFoam
python

Technical Information

There's no official documentation yet so here are some tips for easier navigation through source.

Classes

These contain data to be written to blockMeshDict and also methods for point manipulation and output formatting.

Vertex: an object containing (x, y, z) point and its index in blockMesh. Also formats output so OpenFOAM can read it.
Edge: a collection of two Vertex indexes and a number of Points in between
Face: a collection of exactly 4 Vertexes and optionally 4 Edges. If only some of the 4 edges are curved a None can be passed instead of a list of edge points.
Block: contains Vertex and Edge objects and other block data: patches, number of cells, grading, cell zone, description.
Mesh: holds lists of all blockMeshDict data: Vertex, Edge, Block.

Block Creation

A blockMesh is created from a number of blocks, therefore a Block object is in the center of attention. It is always created from 8 vertices - the order of which follows the sketch on openfoam.com user manual. Edges are added to block by specifying vertex indexes and a list of points in between.

Operations simply provide an interface for calculating those 8 vertices in a user-friendly way, taking care of intricate calculations of points and edges.

Once blocks are created, additional data must/may be added (number of cells, grading, patches, projections). Finally, all blocks must be added to Mesh. That will prepare data for blockMesh and create a blockMeshDict from a template.

Data Preparation

After all blocks have been added, an instance of Mesh class only contains a list of blocks. Each block self-contains its own data. Since blocks share vertices and edges and blockMesh needs separate lists of both, Mesh.prepare_data() will translate all individual blocks' data to format blockMesh will understand:

collect new vertices and re-use existing ones
collect block edges, skipping duplicates
run count and grading calculations on blocks where those are set
assign neighbours of each block, then try to propagate cell counts and gradings through the whole mesh; if that fails, an Exception is raised
gather a list of projected faces and edges

TODO

Unchecked list items from Features
Chaining:
- *FrustumWall.expand()
- *FrustumWall.contract()
- *ElbowWall.contract()
- Box.chain()
- Block.chain() (low-level), or Block.get_face() -> Face
Optimization
Examples
- Ramjet engine
Technical stuff:
- Redefine classes to support modification
- Simplify imports (direct import from classy_blocks instead of specifying complete module paths)
- Package to pypi
- Debugging: connection between block and Shapes, naming
- More tests
- Documentation

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

damogranlabs / classy_blocks

Programming Languages

Labels

Projects that are alternatives of or similar to classy blocks