mesh2flac3d 0.1.0__tar.gz

mesh2flac3d-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,97 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mesh2flac3d"
+version = "0.1.0"
+description = "Convert Gmsh/VTK meshes to Itasca FLAC3D .f3grid, preserving physical groups (ZGROUP/FGROUP) with correct zone winding."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "AI SIM Engenharia Geotecnica" }]
+keywords = ["flac3d", "gmsh", "mesh", "geomechanics", "itasca", "f3grid", "finite-element"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering",
+    "Operating System :: OS Independent",
+]
+dependencies = ["meshio>=5", "numpy>=1.20"]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "gmsh>=4"]
+
+[project.urls]
+Homepage = "https://github.com/Jeanbjoseph/mesh2flac3d"
+Issues = "https://github.com/Jeanbjoseph/mesh2flac3d/issues"
+
+[project.scripts]
+mesh2flac3d = "mesh2flac3d.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mesh2flac3d-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mesh2flac3d-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/mesh2flac3d.egg-info/PKG-INFO

@@ -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/src/mesh2flac3d.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/mesh2flac3d/__init__.py
+src/mesh2flac3d/cli.py
+src/mesh2flac3d/core.py
+src/mesh2flac3d/dat.py
+src/mesh2flac3d.egg-info/PKG-INFO
+src/mesh2flac3d.egg-info/SOURCES.txt
+src/mesh2flac3d.egg-info/dependency_links.txt
+src/mesh2flac3d.egg-info/entry_points.txt
+src/mesh2flac3d.egg-info/requires.txt
+src/mesh2flac3d.egg-info/top_level.txt
+tests/test_convert.py

mesh2flac3d-0.1.0/src/mesh2flac3d.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mesh2flac3d-0.1.0/src/mesh2flac3d.egg-info/entry_points.txt

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

mesh2flac3d-0.1.0/src/mesh2flac3d.egg-info/requires.txt

@@ -0,0 +1,6 @@
+meshio>=5
+numpy>=1.20
+
+[test]
+pytest>=7
+gmsh>=4

mesh2flac3d-0.1.0/src/mesh2flac3d.egg-info/top_level.txt

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

mesh2flac3d-0.1.0/tests/test_convert.py

@@ -0,0 +1,148 @@
+"""End-to-end tests. gmsh is used ONLY to build the fixture mesh, never by the
+package itself. Run: pytest -q  (needs meshio, numpy, gmsh)."""
+
+import os
+import subprocess
+import sys
+
+import numpy as np
+import meshio
+import pytest
+
+import mesh2flac3d as m2f
+
+HERE = os.path.dirname(__file__)
+FIXGEN = os.path.join(HERE, "fixtures", "make_testmesh.py")
+
+
+@pytest.fixture(scope="module")
+def msh(tmp_path_factory):
+    out = tmp_path_factory.mktemp("mesh") / "box3.msh"
+    subprocess.run([sys.executable, FIXGEN, str(out)], check=True)
+    return str(out)
+
+
+def _read_f3grid_zones(path):
+    """Minimal parser: returns points(dict id->xyz) and zones(list of node-id lists)."""
+    pts, zones = {}, []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            s = line.split()
+            if not s:
+                continue
+            if s[0] == "G":
+                pts[int(s[1])] = np.array([float(s[2]), float(s[3]), float(s[4])])
+            elif s[0] == "Z":
+                zones.append([int(x) for x in s[3:]])
+    return pts, zones
+
+
+def _first4_positive(pts, zones):
+    """Every FLAC3D zone must have its first four nodes right-handed
+    (triple product > 0) — the invariant FLAC3D checks on import."""
+    bad = 0
+    for n in zones:
+        p0, p1, p2, p3 = (pts[i] for i in n[:4])
+        if np.dot(np.cross(p1 - p0, p2 - p0), p3 - p0) <= 0:
+            bad += 1
+    return bad
+
+
+def _build_mixed_mesh():
+    """In-memory mesh with wedges (W6) and a pyramid (P5), half of them
+    deliberately inverted, to exercise winding correction without gmsh.
+    Mirrors the case validated live in FLAC3D 7.0 (vtot == 1e6, negzero == 0)."""
+    corners = np.array([[0, 0], [100, 0], [100, 100], [0, 100]], float)
+    zlev = [0.0, -30.0, -60.0, -90.0]
+    pts, idx = [], {}
+    for k, z in enumerate(zlev):
+        for c, (x, y) in enumerate(corners):
+            idx[(c, k)] = len(pts)
+            pts.append([x, y, z])
+    pts = np.array(pts, float)
+    tris = [(0, 1, 2), (0, 2, 3)]
+    wedges, layer = [], []
+    for k in range(3):
+        for a, b, c in tris:
+            wedges.append([idx[(a, k + 1)], idx[(b, k + 1)], idx[(c, k + 1)],
+                           idx[(a, k)], idx[(b, k)], idx[(c, k)]])
+            layer.append(k)
+    wedges = np.array(wedges)
+    for i in range(0, len(wedges), 2):        # invert every other wedge
+        wedges[i] = wedges[i][[3, 4, 5, 0, 1, 2]]
+    base_p = [idx[(0, 0)], idx[(1, 0)], idx[(2, 0)], idx[(3, 0)]]
+    apex = len(pts)
+    pts = np.vstack([pts, [50, 50, 30]])
+    pyr = np.array([[*base_p, apex]])
+    cells = [("wedge", wedges), ("pyramid", pyr)]
+    sets = {}
+    for k, nm in enumerate(["Overburden", "Salt", "Underburden"]):
+        sets[nm] = [np.array([i for i, lk in enumerate(layer) if lk == k]),
+                    np.array([], dtype=int)]
+    sets["Cap"] = [np.array([], dtype=int), np.array([0])]
+    return meshio.Mesh(points=pts, cells=cells, cell_sets=sets)
+
+
+def test_wedge_pyramid_winding(tmp_path):
+    out = str(tmp_path / "wedp5.f3grid")
+    grid = m2f.Grid.from_meshio(_build_mixed_mesh())
+    m2f.write_f3grid(grid, out)
+    pts, zones = _read_f3grid_zones(out)
+    assert len(zones) == 7  # 6 wedges + 1 pyramid
+    assert _first4_positive(pts, zones) == 0
+    assert set(grid.zone_groups) == {"Overburden", "Salt", "Underburden", "Cap"}
+
+
+def test_convert_preserves_groups(msh, tmp_path):
+    out = str(tmp_path / "box3.f3grid")
+    grid = m2f.convert(msh, out)
+
+    # zone groups: the three volume layers must survive
+    assert set(grid.zone_groups) == {"Overburden", "Salt", "Underburden"}
+    # face groups: the three boundary sets must survive as FGROUP
+    assert set(grid.face_groups) == {"Top", "Bottom", "Sides"}
+
+    # every zone assigned to exactly one group (partition of the zone set)
+    total_zones = sum(len(c[1]) for c in grid.zone_cells)
+    grouped = np.concatenate(list(grid.zone_groups.values()))
+    assert len(grouped) == total_zones
+    assert len(np.unique(grouped)) == total_zones
+
+
+def test_no_negative_volume_tets(msh, tmp_path):
+    out = str(tmp_path / "box3.f3grid")
+    m2f.convert(msh, out)
+    pts, zones = _read_f3grid_zones(out)
+    tets = [z for z in zones if len(z) == 4]
+    assert tets, "expected tetrahedra in the fixture"
+    bad = 0
+    for n in tets:
+        p0, p1, p2, p3 = (pts[i] for i in n)
+        # FLAC3D requires positive zone volume: triple product > 0.
+        # (Confirmed by FLAC3D 7.0, which errors on "tet volumes are <= 0".)
+        det = np.dot(np.cross(p1 - p0, p2 - p0), p3 - p0)
+        if det <= 0:
+            bad += 1
+    assert bad == 0, f"{bad} non-positive-volume tetrahedra written"
+
+
+def test_roundtrip_with_meshio_reader(msh, tmp_path):
+    """Our .f3grid must be readable back by meshio's FLAC3D reader."""
+    out = str(tmp_path / "box3.f3grid")
+    m2f.convert(msh, out, keep_faces=False)  # meshio reader focuses on zones
+    back = meshio.read(out)
+    n_tetra = sum(len(cb.data) for cb in back.cells if cb.type == "tetra")
+    assert n_tetra > 0
+
+
+def test_cli(msh, tmp_path):
+    out = str(tmp_path / "cli.f3grid")
+    dat = str(tmp_path / "cli.dat")
+    rc = subprocess.run(
+        [sys.executable, "-m", "mesh2flac3d.cli", msh, out, "--dat", dat],
+        capture_output=True, text=True,
+    )
+    assert rc.returncode == 0, rc.stderr
+    assert os.path.exists(out) and os.path.exists(dat)
+    assert "ZGROUP" in open(out, encoding="utf-8").read()
+    assert "FGROUP" in open(out, encoding="utf-8").read()