Python API

All supported names below are exported from omni_solver_interop_mapdl. The neutral reader, writer, and native array functions do not require OmniSolver; only the two OmniSolver adapter functions import it.

Text and neutral read/write

Function	Contract
`read_dat(path, *, strict=True, validate=True, encoding=None)`	Read an ASCII `.dat` or `.cdb`; large resolved meshes automatically use the native bulk path
`parse_dat(text, *, source="<memory>", strict=True, validate=True)`	Parse an in-memory text deck without executing commands
`render_dat(model)`	Return deterministic semantic MAPDL ASCII
`write_dat(model, path)`	Validate and write `.dat` or `.cdb` text; returns the destination path
`write_neutral_json(model, path)`	Validate and write schema `omni-neutral-mapdl-v1`; returns the destination path
`read_neutral_json(path)`	Read that schema and validate its references

Text output preserves the supported neutral state, not original whitespace or record ordering. SUPPORTED_SUFFIXES and SUPPORTED_BINARY_SUFFIXES expose the admitted filename families; __version__ reports the installed package version.

Strictness, reports, and errors

Strict parsing is the default. A model-mutating command that cannot be represented raises UnsupportedCommandError, including its command, line number, and source text. DeckSyntaxError means a recognized record is malformed. ModelValidationError.issues lists invalid model references or values. All three conversion errors derive from MapdlInteropError.

Use permissive parsing only for inspection:

from omni_solver_interop_mapdl import read_dat

model = read_dat("input.dat", strict=False)
if not model.report.complete:
    for record in model.report.untranslated:
        print(record.line_number, record.command, record.reason)

ParseReport.ignored records recognized non-model or non-executed commands; ParseReport.untranslated records incomplete model translation. ParseReport.requires_preloaded_model identifies a restart or delta deck whose references depend on state outside that file. ParseReport.standalone_complete is false for either untranslated or externally dependent state. Such a model can be serialized as neutral JSON for inspection, but MAPDL text writing, application-sink emission, and OmniSolver dispatch refuse it rather than silently manufacturing the missing base model. Disabling validate postpones reference checking; call NeutralModel.validate() before consuming the model.

Neutral model

NeutralModel is explicit data and intentionally has no solve method. Its collections use the following public record types:

State	Record types
Mesh and attributes	`Node`, `Element`, `ElementType`, `CoordinateSystem`
Properties	`Material`, `Section`, `ArrayParameter`, real-constant dictionaries
Constraints	`Constraint`, `Coupling`, `ConstraintEquation`, `ConstraintEquationTerm`
Loads	`NodalLoad`, `BodyLoad`, `ElementBodyLoad`, `SurfaceLoad`, `BeamSurfaceLoad`
Groups and special state	`Component`, `ElementFaceComponent`, `NonStructuralMass`
Retained setup	`AnalysisControl`, `DocumentedModelRecord`, `CommandRecord`, `ParseReport`

NeutralModel.to_dict() returns the JSON-compatible v1 representation. Use write_neutral_json rather than constructing JSON manually so schema identity and model validation are applied consistently.

Application sinks

ModelSink is the application-owned receiver protocol. Implement its set_* and add_* methods, then call emit_to_sink(model, sink); records are validated and emitted in deterministic order without assembly or solver behavior. ComplexValueSink is the optional extension for complex constraints and nodal loads. If such values are present and the sink does not implement the extension, emission raises instead of discarding the imaginary component.

The sink.py protocol is the authoritative method-signature reference.

Native bulk arrays

These functions call the native C reader and return NumPy-backed frozen data classes:

Function	Return type and contents
`read_native_mesh(path)`	`NativeMesh`: node arrays, element attributes, CSR connectivity, and numeric nodal body loads; check `body_loads_complete`
`read_native_binary_info(path)`	`NativeBinaryInfo`: documented standard and family header values
`read_native_result_nodes(path)`	`NativeResultNodes`: `.rst`/`.rth` LOC IDs, coordinates, and rotations
`read_native_result_elements(path)`	`NativeResultElements`: EID attributes and CSR connectivity
`read_native_result_nodal_solution(path, result_set_index=0)`	`NativeResultNodalSolution`: NSL values in nodal-coordinate-system order
`read_native_result_element_records(path, result_set_index=0)`	`NativeResultElementRecords`: ESL record pointers and implicit-zero counts, without value interpretation
`read_native_full_matrix(path, kind="stiffness")`	`NativeSparseMatrix`: exact stored COO rows, columns, real values, and optional imaginary values
`read_native_emat_headers(path)`	`NativeEmatHeaders`: documented EMAT element pointers, orders, and presence flags

Supported FULL kind values are stiffness, mass, damping, complex_stiffness, and complex_mass. Stored triangular matrices remain triangular and constrained entries are not removed.

Reused high-level binary reader

read_binary(path, **kwargs) delegates .rst, .rth, .full, and .emat files to the retained MIT-licensed reader. It returns that reader's public result or matrix object. The native functions above are preferable when a small, typed array surface is sufficient. Saved .db files are explicitly rejected. Install the optional binary dependency extra for this PyVista/SciPy convenience layer; the native C/NumPy functions are in the minimal installation.

OmniSolver adapter

from omni_solver_interop_mapdl import read_dat, solve_dat, to_omnisolver_model

neutral = read_dat("ds.dat")
destination = to_omnisolver_model(
    neutral,
    require_complete=True,
    analysis="structural",
    runnable_projections=True,
)
result = solve_dat("ds.dat", thread_limit=8)

to_omnisolver_model constructs a destination model through OmniSolver's public declarative API. analysis may select the material view; the source neutral model is unchanged. require_complete=True refuses an incomplete parse.

solve_dat(path, *, solver_options=None, thread_limit=None, runnable_projections=True) strictly reads a static deck, selects the public linear-static, nonlinear-static, inverse-static, or steady-thermal route from its retained controls, and returns the OmniSolver result. It does not invoke MAPDL. Runnable destination reductions emit OmniSolverProjectionWarning and leave neutral/MAPDL output unchanged; pass runnable_projections=False to prefer an exact destination family or a typed OmniSolverTranslationError. The detailed projection boundary is listed under Supported boundary.