Audit MLIR terminology and public API naming

[burgholzer]

🤖 AI text below 🤖

Parent: #2250

Scope

Compare compiler-facing C++ APIs, Python APIs, diagnostics, and documentation with the repository glossary. Identify ambiguous or inconsistent uses of operation, pass, rewrite, conversion, translation, import, export, lowering, legalization, target, payload, static and dynamic, QC, QCO, QTensor, and reference, value, and linear semantics.

Deliverable

Report recommended terminology and any public rename separately, including downstream users, compatibility options, deprecation path, and migration cost. Internal objective corrections may use focused PRs. Do not implement breaking C++ or Python renames without explicit approval.

[denialhaag]

Just so that I don't forget myself, I already noticed one inconsistency a couple of days ago: #2149 (comment)

[denialhaag]

Codex and I came up with the following list now (I have a more complete list locally, but I think the abridged version is a better basis for discussion). I think all of this should be rather straightforward, but I'm not entirely sure when we should actually make the proposed changes: Now or closer to the v4 release when most PRs are merged? 🤔

🤖 AI text below 🤖

The audit identified the following concrete changes:

• Align the complete OpenQASM import surface:

  • fromQASMString / fromQASMFile → fromOpenQASMString / fromOpenQASMFile
  • from_qasm_str / from_qasm_file → from_openqasm_str / from_openqasm_file
  • translateQASM3ToQC → translateOpenQASMToQC
  • mlir::oq3::frontend → mlir::openqasm::frontend
  • --input-format=qasm → --input-format=openqasm

  The frontend accepts versionless OpenQASM and versions 2.0, 3.0, and 3.1, so its input names should use the full, version-generic OpenQASM name. The related documentation and diagnostics should describe that complete version contract.

• Make the mqt-cc output checkpoint explicit: advertise and default to --emit=qc instead of --emit=mlir. For example, QC, QCO, and jeff are all represented using MLIR, so mlir does not identify which representation is emitted.

• Rename CompilerTarget::Operation to CompilerTarget::OperationCapability. The class stores a target capability and calibration data, while mlir::Operation represents an IR operation. The current nested name also shadows mlir::Operation inside CompilerTarget.

• Correct the jeff API descriptions to match the current representation:

  • "Serialize this program as jeff" → "Convert this program to jeff MLIR"
  • "A serialized jeff compiler program" → "A serializable compiler program in the jeff dialect"
  • "Deserialize this program to QCO" → "Convert this program to QCO"

  Serialization and deserialization apply specifically to the byte and file methods.

• Correct several MLIR terminology mismatches, for example:

  • "canonicalization and transformation passes" → "canonicalization patterns and transformation passes"
  • "lowering steps between dialects" → "conversions between dialects"
  • OpenQASM casts with "different value semantics" → "different numeric conversion rules"
  • "barrier gate" → "barrier operation"
  • QTensor "linear typing" → "linear semantics" or "linear ownership" where the text describes the public ownership contract

• Tighten ambiguous public descriptions and diagnostics, for example:

  • "MLIR compiler target" → "MQT compiler target" or "compiler target"
  • "The QC target rejects..." → "The QC translation rejects..."
  • The generic "MLIR operation failed" error → an action-specific or neutral compiler failure message

[burgholzer]

Didn't check the complete list yet, but I would argue closer to the release date would be better/more efficient. I'd see this as final documentation and API polishing.