Coreform-Cubit-Mesh-Export 2.0.0
Cubit mesh export to various formats including Gmsh, Nastran, VTK, and Netgen
Requires Python: >=3.7
Keywords: cubit, mesh, exodus, gmsh, nastran, vtk, netgen, ngsolve, export, coreform

# Coreform Cubit Mesh Export

A Python library for exporting mesh files from Coreform Cubit to various formats.

## Installation

### Install from PyPI (Recommended)
```bash
pip install --upgrade coreform-cubit-mesh-export
```

### Install into Cubit's Python Environment
To use within Cubit's journal scripts (`play "script.py"`) for Gmsh/VTK/Nastran export:

**Windows:**
```bash
"C:\Program Files\Coreform Cubit 2025.3\bin\python3\python.exe" -m pip install coreform-cubit-mesh-export
```

**Linux/Mac:**
```bash
/path/to/cubit/bin/python3/python -m pip install coreform-cubit-mesh-export
```

### Install for Netgen/NGSolve Integration
For `export_netgen()` with high-order curving, install into your own Python environment (not Cubit's bundled Python):

```bash
# Install with ngsolve dependency
pip install coreform-cubit-mesh-export[netgen]

# Or install separately
pip install coreform-cubit-mesh-export ngsolve
```

Then add Cubit's bin path to your script:
```python
import sys
sys.path.append("C:/Program Files/Coreform Cubit 2025.3/bin")
import cubit
```

### Install Development Version from GitHub
```bash
pip install git+https://github.com/ksugahar/Coreform_Cubit_Mesh_Export.git
```

## Supported File Formats

- **Exodus II** ⭁ENEW
  - Cubit's native format (.exo, .e, .g)
  - All element types and orders
  - Nodesets and Sidesets support
  - Large model support (64-bit)
- **Netgen**
  - Direct mesh conversion (no intermediate files)
  - High-order curving via `mesh.Curve()` (order 2, 3, 4, 5, ...)
  - All element types: Tet, Hex, Wedge, Pyramid
- **Gmsh Format**
  - Version 4.1 (with $Entities section, 2D/3D auto-detect)
  - Version 2.2 (full support, 2nd-order elements)
- **Nastran Format**
  - 2D meshes
  - 3D meshes
- **MEG Format** (for ELF)
  - 2D meshes
  - 3D meshes
- **VTK Format**
  - Legacy VTK (.vtk) - auto-detect element order
  - VTK XML (.vtu) - modern format with binary support

## Usage

### Netgen (High-Order Curving)

```python
import cubit
import cubit_mesh_export
import ngsolve

# Create mesh in Cubit
cubit.cmd("create sphere radius 1")
cubit.cmd("volume 1 scheme tetmesh")
cubit.cmd("mesh volume 1")
cubit.cmd("block 1 add tet all in volume 1")
cubit.cmd("block 1 name 'domain'")
cubit.cmd("block 2 add tri all in surface all")
cubit.cmd("block 2 name 'boundary'")

# Export geometry for Curve() support
cubit.cmd('export step "geometry.step" overwrite')

# Convert to NGSolve mesh with high-order curving
ngmesh = cubit_mesh_export.export_netgen(cubit, geometry_file="geometry.step")
mesh = ngsolve.Mesh(ngmesh)
mesh.Curve(3)  # 3rd order curved elements

# Use in FEM analysis
print(mesh.GetMaterials())   # ('domain',)
print(mesh.GetBoundaries())  # ('boundary',)
```

See [docs/export_NetgenMesh.md](docs/export_NetgenMesh.md) for detailed documentation.

### Usage within Cubit

After generating a mesh in Cubit, execute a Python script as follows:

```python
# Cubit command line
play "export_mesh.py"
```

Example content of `export_mesh.py`:

```python
import cubit_mesh_export

# Export to Nastran format (3D)
FileName = 'output/model.nas'
cubit_mesh_export.export_nastran(cubit, FileName, DIM="3D")

# Export to Gmsh format (v2.2, supports 2nd-order elements)
FileName = 'output/model.msh'
cubit_mesh_export.export_gmsh_v2(cubit, FileName)

# Export to VTK format (auto-detects element order)
FileName = 'output/model.vtk'
cubit_mesh_export.export_vtk(cubit, FileName)
```

## Function Reference

### Naming Convention

Functions use **snake_case** naming (e.g., `export_gmsh_v2`). Legacy PascalCase names are available as aliases for backward compatibility.

| Recommended (snake_case) | Legacy (PascalCase) |
|--------------------------|---------------------|
| `export_exodus` | *(already snake_case)* |
| `export_gmsh_v2` | `export_Gmsh_ver2` |
| `export_gmsh_v4` | `export_Gmsh_ver4` |
| `export_nastran` | `export_Nastran` |
| `export_netgen` | `export_NetgenMesh` |
| `export_meg` | *(already snake_case)* |
| `export_vtk` | *(already snake_case)* |
| `export_vtu` | *(already snake_case)* |

### Exodus II Format
- `export_exodus(cubit, filename, overwrite=True, large_model=False)` - Export to Exodus II format
  - Cubit's native format (.exo, .e, .g)
  - Supports all element types and orders
  - `large_model=True` for meshes with >2 billion elements/nodes

### Netgen Format
- `export_netgen(cubit, geometry_file=None)` - Export to `netgen.meshing.Mesh` object
  - Returns mesh ready for `ngsolve.Mesh()` conversion
  - With `geometry_file`: enables `mesh.Curve(order)` for high-order elements
  - Supports: Tet, Hex, Wedge, Pyramid, Tri, Quad

### Gmsh Format
- `export_gmsh_v4(cubit, filename, DIM="auto")` - Export to Gmsh v4.1 format with $Entities section
  - DIM: "auto"/"2D"/"3D"
- `export_gmsh_v2(cubit, filename)` - Export to Gmsh v2.2 format with 2nd-order element support

### Nastran Format
- `export_nastran(cubit, filename, DIM="2D|3D", PYRAM=True|False)` - Export to Nastran BDF format
  - Convert pyramids to degenerate hex with `PYRAM=False` (for JMAG compatibility)

### MEG Format (for ELF)
- `export_meg(cubit, filename, DIM="T|R|K", MGR2=[])` - T: 3D, R: axisymmetric, K: 2D

### VTK Format
- `export_vtk(cubit, filename)` - Export to Legacy VTK format, auto-detects element order
- `export_vtu(cubit, filename, binary=False)` - Export to VTK XML format (.vtu)

## High-Order Element Support

| Format | 1st Order | 2nd Order | 3rd+ Order |
|--------|-----------|-----------|------------|
| Exodus II | ✁E| ✁E| ✁E|
| NGSolve | ✁E| ✁E(via Curve) | ✁E(via Curve) |
| Gmsh v4.1 | ✁E| ✁E| ❁E|
| Gmsh v2.2 | ✁E| ✁E| ❁E|
| VTK/VTU | ✁E| ✁E| ❁E|
| Nastran | ✁E| ❁E| ❁E|

**Note**: Exodus II is Cubit's native format and supports all element orders. NGSolve's `mesh.Curve(order)` generates high-order nodes from geometry.

## Block Registration

This module uses **blocks only** for mesh export (not nodesets or sidesets).

**Why?** In Cubit, only blocks support element order control via `block X element type tetra10`. Nodesets and sidesets lack this capability. By standardizing on blocks, we ensure consistent 2nd order element support across all export formats.

**Boundary conditions** can still be defined using separate blocks:
```
block 1 add tet all in volume 1    # Domain
block 1 name "domain"
block 2 add tri all in surface 1   # Boundary
block 2 name "boundary"
block 1 element type tetra10       # Convert to 2nd order
```

### Geometry vs Mesh Elements in Blocks

Blocks can contain either **mesh elements** or **geometry**. Both are now supported:

```python
# Method 1: Register mesh elements directly (recommended)
block 1 add tet all
block 1 add hex all

# Method 2: Register geometry (volume, surface, curve, vertex)
block 1 add volume 1      # Exports tet/hex/wedge/pyramid in the volume
block 2 add surface 1     # Exports tri/quad on the surface
block 3 add curve 1       # Exports edges on the curve
```

**Behavior by geometry type:**

| Block Contains | Elements Exported |
|----------------|-------------------|
| Volume | tet, hex, wedge, pyramid (3D elements only) |
| Surface | tri, quad (2D elements only) |
| Curve | edge (1D elements only) |
| Vertex | node (0D elements only) |

### Mixed Element Types Warning

When a block contains multiple 3D element types (e.g., tet + hex), a warning is displayed with instructions for 2nd order conversion:

```
WARNING: Block 1 ('mixed') contains multiple 3D element types: hex, tet
  To convert all elements to 2nd order, you need to issue separate commands:
    block 1 element type hex20
    block 1 element type tetra10
```

This warning helps users understand that each element type requires its own conversion command.

## Requirements

- Coreform Cubit 2024.3 or later (provides Python environment and `cubit` module)
- NGSolve/Netgen (optional, for `export_NetgenMesh()` function)

## License

LGPL-2.1 (GNU Lesser General Public License version 2.1)

## Author

Kengo Sugahara (ksugahar@kindai.ac.jp)

## Repository

- GitHub: [https://github.com/ksugahar/Coreform_Cubit_Mesh_Export](https://github.com/ksugahar/Coreform_Cubit_Mesh_Export)
- PyPI: [https://pypi.org/project/coreform-cubit-mesh-export/](https://pypi.org/project/coreform-cubit-mesh-export/)

## Bug Reports & Feature Requests

Please submit via [GitHub Issues](https://github.com/ksugahar/Coreform_Cubit_Mesh_Export/issues).