caexfer 0.1.2

Transfer linear finite-element meshes and results across CAE formats
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

[![Crates.io version](https://img.shields.io/crates/v/caexfer.svg)](https://crates.io/crates/caexfer)
[![Documentation](https://img.shields.io/docsrs/caexfer.svg)](https://docs.rs/caexfer)
[![CI](https://github.com/cmccomb/caexfer/actions/workflows/ci.yml/badge.svg)](https://github.com/cmccomb/caexfer/actions/workflows/ci.yml)
[![Measured Rust line coverage](https://raw.githubusercontent.com/cmccomb/caexfer/coverage-badge/coverage.svg)](https://github.com/cmccomb/caexfer/actions/workflows/coverage.yml)

# caexfer

<p align="center"><img src="https://raw.githubusercontent.com/cmccomb/caexfer/main/assets/logo.svg" alt="caexfer logo" width="320"></p>

**Transfer finite-element meshes and results across formats.**

`caexfer` reads and writes supported subsets of STL, SU2, UNV, Exodus II,
VTU, legacy VTK, Gmsh MSH 4.1/2.2, Abaqus/CalculiX INP, CalculiX FRD,
Nastran BDF, and Nastran OP2. It also reads PCH displacement results when
given a matching mesh. Each conversion reports omissions and assumptions.

## Get started

Requires Rust 1.86 or newer. Install the published CLI from crates.io:

```sh
cargo install caexfer
caexfer --formats
```

Add the published library to your Rust project:

```sh
cargo add caexfer
```

The CLI and library support the same format routes. The examples below use
fixtures from a repository checkout; run them from its root. This sequence
carries nodal results from FRD through VTU to Gmsh MSH 2.2, then reads PCH
results with a matching BDF mesh.

**CLI**

```sh
caexfer convert tests/fixtures/linear-results.frd results.vtu
caexfer convert results.vtu results.msh --msh-version 2.2 \
  --accept-omissions
caexfer convert tests/fixtures/pch-multiple.pch displacements.vtu \
  --mesh tests/fixtures/pch-companion.bdf --subcase 1 \
  --accept-omissions
```

These commands create new files; choose fresh output names when rerunning them.

**Rust library**

```rust
use caexfer::{MshVersion, Options, Result, convert, validate};

fn main() -> Result<()> {
    let source = validate("tests/fixtures/linear-results.frd", &Options::default())?;
    assert!(source.passed);
    let report = convert("tests/fixtures/linear-results.frd", "results.vtu",
                         &Options { accept_omissions: true, ..Options::default() })?;
    for notice in report.omissions {
        eprintln!("{}: {}", notice.stage.name(), notice.detail);
    }
    convert("results.vtu", "results.msh", &Options {
        msh_version: Some(MshVersion::V2_2),
        accept_omissions: true,
        ..Options::default()
    })?;
    convert("tests/fixtures/pch-multiple.pch", "displacements.vtu", &Options {
        mesh: Some("tests/fixtures/pch-companion.bdf".into()),
        subcase: Some(1),
        accept_omissions: true,
        ..Options::default()
    })?;
    Ok(())
}
```

`convert` lists reported losses and assumptions before asking for confirmation.
For scripts, pass the specific `--accept-...` flags named in that list, or use
`--accept-all` to accept every reported change.

## Conversion routes

[![Flowchart of solver inputs, geometry formats, mesh datasets, and companion results connecting through caexfer](https://raw.githubusercontent.com/cmccomb/caexfer/84eb011cc7b7e4214b9e83b2b54016d0f14a149f/assets/conversion-flow.svg)](https://github.com/cmccomb/caexfer/blob/main/assets/conversion-flow.svg)

`caexfer --formats` lists the current readers and writers. Mesh sources can be
converted when the destination supports their cell types and data. VTU, legacy
VTK, MSH, and classic Exodus carry numeric fields within their documented
subsets; FRD carries nodal fields. BDF, INP, STL, SU2, and UNV provide narrower
geometry routes. MSH physical groups become named selections, and SU2 carries
named boundary markers. OP2 and PCH displacement results require a companion
mesh with original node IDs; OP2 can write a selected displacement table, while
PCH is read-only.

## Documentation

- [CLI guide](https://github.com/cmccomb/caexfer/blob/main/docs/CLI.md) covers
  options, confirmation, output replacement, and JSON receipts.
- [Library guide](https://github.com/cmccomb/caexfer/blob/main/docs/LIBRARY.md)
  shows the typed API and acceptance options.
- [Format support](https://github.com/cmccomb/caexfer/blob/main/docs/SUPPORT.md)
  lists the exact readable and writable subsets and their limits.
- [Coverage](https://github.com/cmccomb/caexfer/blob/main/docs/COVERAGE.md)
  explains what the badge measures.