mesh2flac3d 0.1.0__py3-none-any.whl

mesh2flac3d/__init__.py

@@ -0,0 +1,19 @@
+"""
+mesh2flac3d — Export meshes (Gmsh .msh, VTK, ...) to Itasca FLAC3D .f3grid,
+preserving physical groups as zone groups (ZGROUP) and boundary/face groups
+as face groups (FGROUP), with guaranteed right-handed (positive-volume) zones.
+
+Reads via `meshio` (any format it supports); writes a correct FLAC3D grid.
+Does NOT import `gmsh`, so it carries no GPL obligation.
+
+Basic use:
+
+    import mesh2flac3d as m2f
+    m2f.convert("model.msh", "model.f3grid")
+
+Copyright (c) 2026 AI SIM Engenharia Geotecnica. MIT License.
+"""
+
+from .core import convert, write_f3grid, Grid, __version__
+
+__all__ = ["convert", "write_f3grid", "Grid", "__version__"]

mesh2flac3d/cli.py

@@ -0,0 +1,67 @@
+"""Command-line interface: ``mesh2flac3d input.msh output.f3grid``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import convert, __version__
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="mesh2flac3d",
+        description="Convert a mesh (Gmsh .msh, VTK, ...) to FLAC3D .f3grid, "
+        "preserving physical groups as ZGROUP/FGROUP.",
+    )
+    p.add_argument("input", help="input mesh (e.g. model.msh)")
+    p.add_argument("output", nargs="?", help="output .f3grid (default: input with .f3grid)")
+    p.add_argument("--no-faces", action="store_true",
+                   help="do not export 2D physical groups as faces/FGROUP")
+    p.add_argument("--float-fmt", default=".10e", help="coordinate format (default: .10e)")
+    p.add_argument("--slot", default="Default", help="FLAC3D group slot name")
+    p.add_argument("--input-format", default=None,
+                   help="force meshio input format instead of inferring")
+    p.add_argument("--dat", metavar="FILE", default=None,
+                   help="also write a FLAC3D command-file skeleton (.dat)")
+    p.add_argument("-q", "--quiet", action="store_true", help="suppress summary")
+    p.add_argument("--version", action="version", version=f"mesh2flac3d {__version__}")
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    output = args.output
+    if output is None:
+        output = args.input.rsplit(".", 1)[0] + ".f3grid"
+
+    grid = convert(
+        args.input, output,
+        keep_faces=not args.no_faces,
+        float_fmt=args.float_fmt,
+        slot=args.slot,
+        input_format=args.input_format,
+    )
+
+    if args.dat:
+        from .dat import write_dat_skeleton
+        write_dat_skeleton(args.dat, output, grid)
+
+    if not args.quiet:
+        nz = sum(len(c[1]) for c in grid.zone_cells)
+        nf = sum(len(c[1]) for c in grid.face_cells)
+        print(f"[mesh2flac3d] {args.input} -> {output}")
+        print(f"  points: {len(grid.points)}  zones: {nz}  faces: {nf}")
+        if grid.zone_groups:
+            print("  zone groups: " + ", ".join(
+                f"{k}({len(v)})" for k, v in grid.zone_groups.items()))
+        if grid.face_groups:
+            print("  face groups: " + ", ".join(
+                f"{k}({len(v)})" for k, v in grid.face_groups.items()))
+        if args.dat:
+            print(f"  command skeleton: {args.dat}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mesh2flac3d/core.py

@@ -0,0 +1,248 @@
+"""Core conversion logic: meshio Mesh -> FLAC3D .f3grid.
+
+The FLAC3D grid (.f3grid) ASCII format used here:
+
+    * GRIDPOINTS
+    G <gid> <x> <y> <z>
+    * ZONES
+    Z <T4|W6|P5|B8> <zid> <n1> <n2> ...
+    * ZONE GROUPS
+    ZGROUP "<name>" SLOT <slot>
+      <zid> <zid> ...
+    * FACES
+    F <T3|Q4> <fid> <n1> <n2> ...
+    * FACE GROUPS
+    FGROUP "<name>" SLOT <slot>
+      <fid> <fid> ...
+
+Node/zone/face IDs are 1-based. Zones and faces have independent ID spaces.
+Zone connectivity is reordered so the first four corner nodes form a
+right-handed system (positive volume) — FLAC3D rejects inverted zones.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__version__ = "0.1.0"
+
+# meshio cell type -> FLAC3D keyword
+MESHIO_TO_FLAC3D_TYPE = {
+    "tetra": "T4",
+    "pyramid": "P5",
+    "wedge": "W6",
+    "hexahedron": "B8",
+    "triangle": "T3",
+    "quad": "Q4",
+}
+
+# 3D (zone) vs 2D (face) meshio types, mapping any high-order variant to its
+# linear corner topology (we export corner nodes only).
+ZONE_TYPES = {
+    "tetra": "tetra", "tetra10": "tetra",
+    "pyramid": "pyramid", "pyramid13": "pyramid",
+    "wedge": "wedge", "wedge12": "wedge", "wedge15": "wedge", "wedge18": "wedge",
+    "hexahedron": "hexahedron", "hexahedron20": "hexahedron",
+    "hexahedron24": "hexahedron", "hexahedron27": "hexahedron",
+}
+FACE_TYPES = {
+    "triangle": "triangle", "triangle6": "triangle", "triangle7": "triangle",
+    "quad": "quad", "quad8": "quad", "quad9": "quad",
+}
+
+# Node reordering meshio -> FLAC3D, and the mirror ordering used when the first
+# variant yields a left-handed (negative) zone.
+ORDER = {
+    "tetra": [0, 1, 2, 3],
+    "pyramid": [0, 1, 3, 4, 2],
+    "wedge": [0, 1, 3, 2, 4, 5],
+    "hexahedron": [0, 1, 3, 4, 2, 7, 5, 6],
+}
+ORDER_MIRROR = {
+    "tetra": [0, 2, 1, 3],
+    "pyramid": [0, 3, 1, 4, 2],
+    "wedge": [0, 2, 3, 1, 5, 4],
+    "hexahedron": [0, 3, 1, 4, 2, 5, 7, 6],
+}
+
+# cell_set keys produced by meshio readers that are not real physical groups.
+_INTERNAL_SET_PREFIXES = ("gmsh:", "medit:", "cell_set-")
+
+
+def _is_internal_key(key: str) -> bool:
+    return any(key.startswith(p) for p in _INTERNAL_SET_PREFIXES)
+
+
+def _reorder_zone(points, conn, key):
+    """Reorder one block of zone connectivity to right-handed FLAC3D order.
+
+    `conn` is (n, k) corner indices into `points`; `key` is the linear type.
+    FLAC3D requires each zone to have positive volume: the first four corner
+    nodes must form a right-handed system, i.e. the scalar triple product
+    (p1-p0)x(p2-p0)-(p3-p0) > 0. (Verified against FLAC3D 7.0, which rejects a
+    grid with "tet volumes are <= 0" otherwise.) Returns (n, k) reordered so
+    every zone imports without a negative-volume error.
+    """
+    o1 = ORDER[key]
+    o2 = ORDER_MIRROR[key]
+    reordered = conn[:, o1]
+    p = points[reordered[:, :4]]
+    a = p[:, 1] - p[:, 0]
+    b = p[:, 2] - p[:, 0]
+    c = p[:, 3] - p[:, 0]
+    det = np.einsum("ij,ij->i", np.cross(a, b), c)
+    # keep o1 where it already yields positive volume (det > 0); else mirror it
+    out = np.where((det > 0)[:, None], conn[:, o1], conn[:, o2])
+    return out
+
+
+class Grid:
+    """A FLAC3D grid ready to be written.
+
+    Built from a meshio Mesh. Splits cells into zones (3D) and faces (2D),
+    fixes zone winding, and resolves physical groups into zone/face groups
+    keyed by name.
+    """
+
+    def __init__(self, points, zone_cells, face_cells, zone_groups, face_groups):
+        self.points = points                # (npts, 3) float
+        self.zone_cells = zone_cells        # list of (flac3d_type, (n,k) int, base_id)
+        self.face_cells = face_cells        # list of (flac3d_type, (n,k) int, base_id)
+        self.zone_groups = zone_groups      # {name: np.array of 1-based zone ids}
+        self.face_groups = face_groups      # {name: np.array of 1-based face ids}
+
+    @classmethod
+    def from_meshio(cls, mesh, keep_faces=True):
+        points = np.asarray(mesh.points, dtype=float)
+        if points.shape[1] == 2:  # promote 2D coords to 3D
+            points = np.column_stack([points, np.zeros(len(points))])
+
+        # Assign global 1-based ids per block; map block index -> id offset.
+        zone_cells, face_cells = [], []
+        zone_block_base = {}   # block_index -> first zone id (1-based)
+        face_block_base = {}
+        zid = 0
+        fid = 0
+        for bi, cb in enumerate(mesh.cells):
+            ct = cb.type
+            data = np.asarray(cb.data)
+            if ct in ZONE_TYPES:
+                key = ZONE_TYPES[ct]
+                corners = data[:, : len(ORDER[key])]
+                conn = _reorder_zone(points, corners, key)
+                zone_block_base[bi] = zid + 1
+                zone_cells.append((MESHIO_TO_FLAC3D_TYPE[key], conn, zid + 1))
+                zid += len(conn)
+            elif keep_faces and ct in FACE_TYPES:
+                key = FACE_TYPES[ct]
+                ncorner = 3 if key == "triangle" else 4
+                conn = data[:, :ncorner]
+                face_block_base[bi] = fid + 1
+                face_cells.append((MESHIO_TO_FLAC3D_TYPE[key], conn, fid + 1))
+                fid += len(conn)
+
+        zone_groups = cls._resolve_groups(mesh, zone_block_base, ZONE_TYPES)
+        face_groups = (
+            cls._resolve_groups(mesh, face_block_base, FACE_TYPES)
+            if keep_faces else {}
+        )
+        return cls(points, zone_cells, face_cells, zone_groups, face_groups)
+
+    @staticmethod
+    def _resolve_groups(mesh, block_base, type_filter):
+        """Turn meshio cell_sets into {name: 1-based global ids} for the given
+        cell family (zone or face). Falls back to cell_data gmsh:physical if no
+        named cell_sets exist."""
+        groups = {}
+        cell_sets = getattr(mesh, "cell_sets", None) or {}
+        for name, per_block in cell_sets.items():
+            if _is_internal_key(name):
+                continue
+            ids = []
+            for bi, local in enumerate(per_block):
+                if bi not in block_base or local is None:
+                    continue
+                local = np.asarray(local)
+                if local.size == 0:
+                    continue
+                ids.append(local + block_base[bi])
+            if ids:
+                groups[name] = np.unique(np.concatenate(ids))
+        return groups
+
+
+def _write_table(f, ids, per_line=10):
+    ids = np.asarray(ids, dtype=int)
+    for i in range(0, len(ids), per_line):
+        f.write("  " + " ".join(str(v) for v in ids[i : i + per_line]) + "\n")
+
+
+def write_f3grid(grid: Grid, path, float_fmt=".10e", slot="Default"):
+    """Write a Grid to a FLAC3D .f3grid ASCII file."""
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(f"* FLAC3D grid produced by mesh2flac3d {__version__}\n")
+
+        f.write("* GRIDPOINTS\n")
+        fmt = "G {:d} " + " ".join(["{:" + float_fmt + "}"] * 3) + "\n"
+        for i, (x, y, z) in enumerate(grid.points, start=1):
+            f.write(fmt.format(i, x, y, z))
+
+        f.write("* ZONES\n")
+        for ftype, conn, base in grid.zone_cells:
+            for j, row in enumerate(conn):
+                zid = base + j
+                nodes = " ".join(str(int(v) + 1) for v in row)
+                f.write(f"Z {ftype} {zid} {nodes}\n")
+
+        if grid.zone_groups:
+            f.write("* ZONE GROUPS\n")
+            for name, ids in grid.zone_groups.items():
+                f.write(f'ZGROUP "{name}" SLOT "{slot}"\n')
+                _write_table(f, ids)
+
+        if grid.face_cells:
+            f.write("* FACES\n")
+            for ftype, conn, base in grid.face_cells:
+                for j, row in enumerate(conn):
+                    fid = base + j
+                    nodes = " ".join(str(int(v) + 1) for v in row)
+                    f.write(f"F {ftype} {fid} {nodes}\n")
+
+        if grid.face_groups:
+            f.write("* FACE GROUPS\n")
+            for name, ids in grid.face_groups.items():
+                f.write(f'FGROUP "{name}" SLOT "{slot}"\n')
+                _write_table(f, ids)
+
+
+def convert(input_path, output_path, keep_faces=True, float_fmt=".10e",
+            slot="Default", input_format=None):
+    """Read a mesh (any meshio-supported format) and write a FLAC3D .f3grid.
+
+    Parameters
+    ----------
+    input_path : str
+        Source mesh (e.g. Gmsh ``.msh``). Physical volume groups become zone
+        groups; physical surface groups become face groups.
+    output_path : str
+        Destination ``.f3grid``.
+    keep_faces : bool
+        Export 2D physical groups as FLAC3D faces/FGROUP (for boundary
+        conditions). Set False to export zones only.
+    float_fmt : str
+        Coordinate format spec.
+    slot : str
+        FLAC3D group slot name.
+    input_format : str, optional
+        Force a meshio input format instead of inferring from the extension.
+
+    Returns
+    -------
+    Grid
+    """
+    import meshio  # imported lazily; meshio is MIT-licensed
+
+    mesh = meshio.read(input_path, file_format=input_format)
+    grid = Grid.from_meshio(mesh, keep_faces=keep_faces)
+    write_f3grid(grid, output_path, float_fmt=float_fmt, slot=slot)
+    return grid

mesh2flac3d/dat.py

@@ -0,0 +1,40 @@
+"""Optional FLAC3D command-file (.dat) skeleton generator.
+
+Emits a *generic* starting script that imports the grid and stubs out a
+constitutive model assignment per zone group and a boundary condition per face
+group. It contains no project-specific parameters — the user fills those in.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def write_dat_skeleton(path, f3grid_path, grid):
+    grid_name = os.path.basename(f3grid_path)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write("; FLAC3D command skeleton generated by mesh2flac3d\n")
+        f.write("; Fill in constitutive models, properties and BC values.\n\n")
+        f.write("model new\n")
+        f.write("model large-strain off\n")
+        f.write(f"zone import '{grid_name}'\n\n")
+
+        f.write("; --- Constitutive model per zone group ---\n")
+        if grid.zone_groups:
+            for name in grid.zone_groups:
+                f.write(f"zone cmodel assign elastic range group '{name}'\n")
+                f.write(f"; zone property young 1e9 poisson 0.3 range group '{name}'\n")
+        else:
+            f.write("; (no zone groups found)\n")
+        f.write("\n")
+
+        f.write("; --- Boundary conditions per face group ---\n")
+        if grid.face_groups:
+            for name in grid.face_groups:
+                f.write(f"; zone face apply velocity-normal 0 range group '{name}'\n")
+        else:
+            f.write("; (no face groups found)\n")
+        f.write("\n")
+
+        f.write("; model gravity 0 0 -9.81\n")
+        f.write("; model solve\n")

mesh2flac3d-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: mesh2flac3d
+Version: 0.1.0
+Summary: Convert Gmsh/VTK meshes to Itasca FLAC3D .f3grid, preserving physical groups (ZGROUP/FGROUP) with correct zone winding.
+Author: AI SIM Engenharia Geotecnica
+License: MIT
+Project-URL: Homepage, https://github.com/Jeanbjoseph/mesh2flac3d
+Project-URL: Issues, https://github.com/Jeanbjoseph/mesh2flac3d/issues
+Keywords: flac3d,gmsh,mesh,geomechanics,itasca,f3grid,finite-element
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: meshio>=5
+Requires-Dist: numpy>=1.20
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: gmsh>=4; extra == "test"
+Dynamic: license-file
+
+# mesh2flac3d
+
+[![CI](https://github.com/Jeanbjoseph/mesh2flac3d/actions/workflows/ci.yml/badge.svg)](https://github.com/Jeanbjoseph/mesh2flac3d/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Convert meshes (Gmsh `.msh`, VTK, and anything [meshio](https://github.com/nschloe/meshio) reads) to **Itasca FLAC3D** `.f3grid` grids — **preserving physical groups**:
+
+- **Volume** physical groups → **`ZGROUP`** (zone groups)
+- **Surface** physical groups → **`FGROUP`** (face groups, for boundary conditions)
+- **Correct zone winding**: every zone is reordered to FLAC3D's convention, so you never get *negative-volume zone* errors on import.
+
+It reads meshes through `meshio` (MIT) and **does not import `gmsh`**, so it carries no GPL obligation — you can use it freely, including in commercial workflows.
+
+## Why not just use meshio?
+
+`meshio` has a FLAC3D writer, but for a typical geomechanics mesh (volume **and** surface physical groups) it currently:
+
+- **crashes** (`TypeError` in `split_f_z`) when both zone and face groups are present, and
+- **drops all 2D groups** (`"FLAC3D format only supports 3D cells. Skipping triangle…"`), so you lose the face groups you need for boundary conditions, and
+- does not guarantee zone orientation.
+
+`mesh2flac3d` is a focused, correct writer built for that exact case.
+
+## Install
+
+```bash
+pip install mesh2flac3d          # once published
+# or, from source:
+pip install -e .
+```
+
+## Command line
+
+```bash
+mesh2flac3d model.msh model.f3grid
+mesh2flac3d model.msh                 # -> model.f3grid
+mesh2flac3d model.msh out.f3grid --dat out.dat   # also write a FLAC3D command skeleton
+mesh2flac3d model.msh --no-faces      # zones only
+```
+
+Example output:
+
+```
+[mesh2flac3d] model.msh -> model.f3grid
+  points: 350  zones: 1218  faces: 522
+  zone groups: Underburden(401), Salt(414), Overburden(403)
+  face groups: Top(90), Bottom(90), Sides(342)
+```
+
+## Python API
+
+```python
+import mesh2flac3d as m2f
+
+grid = m2f.convert("model.msh", "model.f3grid")
+print(grid.zone_groups.keys())   # dict_keys(['Underburden', 'Salt', 'Overburden'])
+print(grid.face_groups.keys())   # dict_keys(['Top', 'Bottom', 'Sides'])
+```
+
+## Supported elements
+
+| Family | Gmsh / meshio          | FLAC3D |
+|--------|------------------------|--------|
+| Zones  | tetra                  | T4     |
+|        | pyramid                | P5     |
+|        | wedge / prism          | W6     |
+|        | hexahedron             | B8     |
+| Faces  | triangle               | T3     |
+|        | quad                   | Q4     |
+
+High-order variants (tetra10, hexahedron20, …) are exported using their linear
+corner nodes.
+
+## In Gmsh, name your groups
+
+Give your regions and boundaries **Physical Groups** with names — those names
+become the FLAC3D group names:
+
+```
+Physical Volume("Salt")  = {2};
+Physical Surface("Top")  = {4};
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest -q
+```
+
+The test fixture is generated with Gmsh (`tests/fixtures/make_testmesh.py`);
+Gmsh is a **test-only** dependency, never used by the package at runtime.
+
+## License
+
+MIT © AI SIM Engenharia Geotécnica. FLAC3D and Itasca are trademarks of Itasca
+Consulting Group; this project is independent and not affiliated with Itasca.

mesh2flac3d-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mesh2flac3d/__init__.py,sha256=8CCQYJ_M4ZVcy3nVw1PSbI0gUd3Risk8KGWb1wCD0ZA,647
+mesh2flac3d/cli.py,sha256=4Ry4kXDYgi6H-VQrr3tpFnv599khuOYLro5hSYfI69I,2472
+mesh2flac3d/core.py,sha256=pQQ1BdRepm0u_1WFTEKrw9SZfy-RtW7pf9c1R16l-cU,9110
+mesh2flac3d/dat.py,sha256=82AvV6qhhKEP3GQkQG1WQ6V0RPMCHcddKhH-jM15aeM,1548
+mesh2flac3d-0.1.0.dist-info/licenses/LICENSE,sha256=TF3LBXkec1FJ1k8HniHBuFOPQM_03pbmE_RScq1fCeQ,1085
+mesh2flac3d-0.1.0.dist-info/METADATA,sha256=tCDCUfzYWQYlNC2qptLXbWqxjt2QgZUoKRHj2VAA0zk,4322
+mesh2flac3d-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mesh2flac3d-0.1.0.dist-info/entry_points.txt,sha256=L7rFUmbOwaANdYRCEZRPit_Nhc8JqXTfYOlxrMwSIzM,53
+mesh2flac3d-0.1.0.dist-info/top_level.txt,sha256=MVEVbn8wswTsmbRMEu_Q4zcHKP4Qwolen120U0YQyDk,12
+mesh2flac3d-0.1.0.dist-info/RECORD,,

mesh2flac3d-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mesh2flac3d-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mesh2flac3d = mesh2flac3d.cli:main

mesh2flac3d-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI SIM Engenharia Geotecnica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mesh2flac3d-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mesh2flac3d