calphad-io 0.1.1__tar.gz

calphad_io-0.1.1/.gitignore

@@ -0,0 +1,55 @@
+# Secrets -- never commit these
+*.key
+*.pem
+*.p12
+*.pfx
+.env
+.env.*
+!.env.example
+secrets/
+credentials.json
+*.token
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Editors and OS
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Scratch
+/tmp/
+scratch/

calphad_io-0.1.1/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-04
+
+### Changed
+
+- Packaging and release metadata only; no code changes. Added complete PyPI
+  metadata (PEP 639 `license` expression, author, project URLs and classifiers)
+  and a Trusted Publishing (OIDC) release workflow that publishes on `v*` tags.
+- README install instructions corrected: `calphad-io` is not yet published to
+  PyPI, so the non-working `pip install calphad-io` command was replaced with a
+  working install-from-source command.
+
+## [0.1.0] - 2026-09-29
+
+Initial release.
+
+### Added
+
+- **TDB reader and writer.** Parses `ELEMENT`, `SPECIES`, `FUNCTION`,
+  `TYPE_DEFINITION`, `DEFINE_SYSTEM_DEFAULT`, `DEFAULT_COMMAND`, `PHASE`,
+  `CONSTITUENT` and `PARAMETER`, honouring Thermo-Calc's abbreviated keywords
+  (`CONST`, `PARA`, `TYPE_DEF`, `TEMP_LIM`) and its `$` comment syntax. Commands
+  the library does not understand are preserved verbatim rather than discarded.
+- **Byte-exact TDB round-trip.** A database that is read and written back
+  without modification is emitted from its original source text and is
+  byte-for-byte identical to the input.
+- **DAT reader and writer.** Parses the ChemSage/FactSage format including
+  `IDMX`, `RKMP`, `RKMPM`, `SUBL`, `SUBLM`, `QKTO`, `SUBQ` and `SUBG` phase
+  models, with per-endmember thermodynamic data options, P-T molar-volume terms,
+  magnetic factors, QKTO chemical groups, MQMQA quadruplet coordinations and
+  chemical-group overrides.
+- **Semantically exact DAT round-trip.** Every element, phase, endmember,
+  interval coefficient, excess term and magnetic term is preserved exactly, and
+  every number is emitted in a form that converts back to the identical
+  `float`.
+- **Validator.** 20 finding codes across `error`, `warning` and `info`
+  severities, returned as structured findings. `validate()` never raises.
+- **CLI** with `info`, `parse`, `validate` and `convert` subcommands, all
+  supporting `--json`, with stable exit codes.
+- **Zero runtime dependencies.** Pure standard library, Python 3.10+.
+- Test suite built on 26 real databases from pycalphad and Thermochimica
+  (9 TDB, 17 DAT; 25 round-trip cleanly and 1 is refused by design), plus
+  nine deliberately corrupted fixtures.
+
+### Notes
+
+- Cross-format conversion (TDB to DAT and DAT to TDB) is deliberately refused.
+  Neither direction can be done faithfully from the information the other format
+  carries, and guessing would produce a file that computes the wrong energy.
+- Round-trip fidelity is verified against `pycalphad` as an independent reader:
+  it reports all 25 regenerated databases it can read as semantically identical
+  to the originals, including model hints. (`FeMnCaS-1.dat` uses `SUBI`, which
+  pycalphad cannot read either, so it is refused rather than compared.)
+- That comparison is reproducible end to end via `scripts/generate.py` and
+  `scripts/verify.py`; see `scripts/README.md`.

calphad_io-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing
+
+Thanks for considering a contribution. This library exists to make CALPHAD
+databases safe to move between tools, and the most valuable contributions are
+**real databases** and **bug reports backed by one**.
+
+## Before you write code, read this
+
+`calphad-io` is a workaround, not a destination. `pycalphad` PR
+[#422](https://github.com/pycalphad/pycalphad/pull/422) already implements much
+of the same thing and has been open, unmerged and dormant since 2022. If you are
+here to improve `.DAT` writing in general, **your work is probably more valuable
+applied there than here.**
+
+Concretely, if you are about to implement a feature:
+
+1. Check whether #422 already has it.
+2. If it does, consider contributing the *evidence* instead — a test fixture, a
+   round-trip case, a bug report with a real database — to that pull request.
+3. Only add it here if the goal is specifically to keep a standalone,
+   dependency-free library working.
+
+Contributions that improve the format knowledge (new fixtures, newly documented
+quirks, corrections to the `## Limitations` section) are welcome either way, and
+are the ones most likely to outlive this project.
+
+## Getting set up
+
+```bash
+git clone https://github.com/beduldul/calphad-io
+cd calphad-io
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The suite runs in under a second and needs no network access.
+
+## The two rules that matter
+
+**1. Round-trip fidelity is the headline feature.** Any change to the readers or
+writers must keep `pytest tests/test_roundtrip.py` green. If you add support for
+a construct, add the file that exercises it to `tests/data/`.
+
+**2. A validator that cries wolf is worse than none.** Every check must be
+justified against a real file. Before adding a finding code, ask: *does a
+healthy database ever trip this?* If yes, it is a `warning` or an `info`, not an
+`error` -- or it is not a finding at all. Several checks in `validate.py` carry a
+comment explaining the real file that taught us the rule; please do the same.
+
+## Reporting a bug
+
+The single most useful thing you can attach is a database that reproduces it. If
+you cannot share the file, reduce it to a minimal snippet and say which construct
+is involved.
+
+For a round-trip bug, please include:
+
+```python
+import calphad_io
+db = calphad_io.load("your-file.TDB")
+print(calphad_io.dumps(db) == open("your-file.TDB").read())
+```
+
+## Adding a database fixture
+
+1. Drop the file in `tests/data/`.
+2. Check the licence permits redistribution, and note the source in your pull
+   request. Databases from pycalphad and Thermochimica are already present.
+3. Run the suite. A new file is automatically picked up by the parametrised
+   tests in `tests/conftest.py`.
+4. If the library refuses the file, add it to `UNSUPPORTED` in `conftest.py`
+   with the reason, and open an issue.
+
+## Style
+
+- Typed throughout. `mypy --strict` and `ruff` are configured in
+  `pyproject.toml`; both must pass.
+- No runtime dependencies. The formats are text; do not reach for NumPy.
+- Frozen dataclasses for anything in the object model. Return new objects
+  instead of mutating.
+- Comments should explain *why*, especially where a real file forced an
+  unexpected decision. Those comments are the most valuable documentation in
+  this codebase.
+
+## What is out of scope
+
+- Thermodynamic evaluation, phase-diagram calculation, model fitting. This is an
+  I/O library; it deliberately has no opinion about whether a model is
+  physically sensible.
+- Cross-format conversion. See the README for why it is refused.
+- FactSage 8.1 and later DAT files.
+
+## Commits and pull requests
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`).
+Keep pull requests focused. If you change the public API or add a finding code,
+update `README.md` in the same pull request.

calphad_io-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beduldul
+
+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.

calphad_io-0.1.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: calphad-io
+Version: 0.1.1
+Summary: Read, write and validate CALPHAD thermodynamic databases (Thermo-Calc .TDB and ChemSage/FactSage .DAT)
+Project-URL: Homepage, https://github.com/beduldul/calphad-io
+Project-URL: Repository, https://github.com/beduldul/calphad-io
+Project-URL: Source, https://github.com/beduldul/calphad-io
+Project-URL: Issues, https://github.com/beduldul/calphad-io/issues
+Project-URL: Changelog, https://github.com/beduldul/calphad-io/blob/main/CHANGELOG.md
+Author-email: Abdul Afif Al Kaysan <alkaysan07@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calphad,chemsage,factsage,materials-science,phase-diagram,tdb,thermo-calc,thermodynamics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![CI](https://github.com/beduldul/calphad-io/actions/workflows/ci.yml/badge.svg)](https://github.com/beduldul/calphad-io/actions/workflows/ci.yml)
+# calphad-io
+
+**Read, write and validate CALPHAD thermodynamic databases — Thermo-Calc `.TDB`
+and ChemSage/FactSage `.DAT` — with zero runtime dependencies.**
+
+## Read this first: this library is not the first attempt
+
+Before you adopt `calphad-io`, you should know what it is and is not.
+
+**There is already a ChemSage `.DAT` writer for pycalphad. It was written, and
+then it was abandoned before it could be merged.**
+
+* [`pycalphad` PR **#422**, "ENH: Implement writing of ChemSage DAT files"](https://github.com/pycalphad/pycalphad/pull/422)
+  is **open and unmerged**. It was opened **2022-06-17**, contains **97 commits,
+  all of them from 2022**, and is **+1042/−3 to a single file**.
+* Its first review was `CHANGES_REQUESTED`, asking for tests. A maintainer
+  replied *"this is still high on my list"* in **August 2022**, and it has sat
+  since. The pull request has been dormant for four years.
+
+So the honest framing is **not** "no tool exists". It is:
+
+> **The tool was written and abandoned before merge, and is not installable by
+> anyone.**
+
+That distinction matters, and it changes what you should do with this project.
+
+### If you need a `.DAT` writer, consider helping #422 first
+
+`calphad-io` exists because a usable artifact did not. It is not an argument that
+the existing work should be discarded — it is a workaround for the fact that
+#422 never landed. **If you use this library, please also consider contributing
+to #422 or linking it from there.** The goal is for the CALPHAD community to have
+a working DAT writer, not for this library to win. A revived #422 in pycalphad —
+where the maintainers, the reviewers and the test suite already are — is a better
+outcome than a parallel implementation.
+
+The one thing `calphad-io` can offer that discussion is *evidence*: a corpus of
+real databases and a round-trip harness that reads, writes and re-verifies them.
+That evidence is more useful applied to #422 than hoarded here.
+
+## The problem
+
+CALPHAD databases are the input to every thermodynamic calculation, and both
+formats in circulation are text. Yet there is no general-purpose,
+dependency-free library that reads *and writes* both:
+
+* `pycalphad` reads `.TDB` and `.DAT` and writes `.TDB`, but has no `.DAT`
+  writer. Its maintainer explained why in
+  [pycalphad#413](https://github.com/pycalphad/pycalphad/issues/413) (open since
+  2022-05-12): *"That was my main deterrent for not implementing a DAT writer, as
+  I don't have FactSage to test against as a reference implementation."*
+* `Thermochimica` consumes `.DAT` and has no general writer.
+* `OpenCalphad`'s `save_datformat` routine is marked in its own source as
+  *"writes a SOLGASMIX DAT format file. **not (ever?) finished**"*.
+* The only widely-used tooling around the format is a syntax highlighter
+  ([`amkrajewski/TDB-Highlighter`](https://github.com/amkrajewski/TDB-Highlighter),
+  13 stars).
+
+`calphad-io` fills that gap. It is a parser, a writer and a validator. It does
+**not** compute thermodynamics — it gets your database *to* the solver intact.
+
+## Scope, stated honestly
+
+| | `.TDB` | `.DAT` |
+|---|---|---|
+| Read | yes | yes (subset — see Limitations) |
+| Write | **byte-for-byte identical** round-trip | semantically identical round-trip |
+| Validate | yes | yes |
+| Convert to the other format | **refused, deliberately** | **refused, deliberately** |
+
+* **TDB round-trip is byte-exact.** Nine real databases — including the 296 KB
+  `COST507.tdb` — parse and re-emit to the identical bytes.
+* **DAT round-trip is semantically exact.** Every element, phase, endmember,
+  interval coefficient, excess term and magnetic term is preserved, and every
+  number is emitted in a form that converts back to the identical `float`.
+  Formatting and comments are not preserved: DAT files are hand-edited in
+  practice and no reader in the ecosystem depends on column positions.
+* **Both are verified against an independent implementation.** `pycalphad` reads
+  the regenerated files as *identical* — same elements, species, phases,
+  sublattice constituents, model hints and every parameter expression — for
+  **all 25 regenerated files** — every file this library can read. This is
+  reproducible end to end: [`scripts/generate.py`](scripts/generate.py)
+  regenerates the corpus from `tests/data/` with this library, and
+  [`scripts/verify.py`](scripts/verify.py) re-checks it against the originals
+  with pycalphad. See [`scripts/README.md`](scripts/README.md).
+* **Three of them were also compared thermodynamically.** For three regenerated
+  files the computed Gibbs energy was compared across their temperature ranges
+  and was **bit-identical** (relative difference exactly `0.00e+00`). This
+  comparison is not scripted in this repository.
+
+## Install
+
+**Not yet on PyPI** — there is no `pip install calphad-io` yet. Install from
+the repository:
+
+```bash
+pip install git+https://github.com/beduldul/calphad-io.git
+```
+
+To work on the library itself, clone it and install it editable, as described
+in [`CONTRIBUTING.md`](CONTRIBUTING.md):
+
+```bash
+git clone https://github.com/beduldul/calphad-io
+cd calphad-io
+pip install -e ".[dev]"
+```
+
+No dependencies. Python 3.10+.
+
+## Use
+
+### Library
+
+```python
+import calphad_io
+
+db = calphad_io.load("steel.TDB")
+print(db.summary())
+# {'format': 'tdb', 'elements': 29, 'phases': 243, 'parameters': 1907, ...}
+
+for phase in db.phases:
+    print(phase.name, phase.constituent_names())
+
+# Round-trip: TDB comes back byte-for-byte
+assert calphad_io.dumps(db) == open("steel.TDB").read()
+
+# Validate before it reaches a solver
+for finding in calphad_io.validate(db):
+    print(finding)
+```
+
+### Command line
+
+```bash
+calphad-io info     steel.TDB
+calphad-io parse    steel.TDB
+calphad-io validate steel.TDB
+calphad-io validate steel.TDB --json
+calphad-io convert  steel.TDB --to tdb -o canonical.TDB
+```
+
+Exit codes are stable: `0` clean, `1` validation errors or a refused conversion,
+`2` unparseable, `3` bad usage.
+
+## The object model
+
+Eight immutable frozen dataclasses in `calphad_io.model` (`Format` is a plain
+class of string constants, not a dataclass), shared by both formats. Nothing is
+mutated after construction; transformations return new objects.
+
+```
+Database
+├── format: "tdb" | "dat"
+├── elements:  tuple[Element]        name, reference_phase, mass, h298, s298
+├── species:   tuple[Species]        name, stoichiometry, charge
+├── phases:    tuple[Phase]          name, sublattices, type_code, model,
+│                                    kind, is_dummy, is_stoichiometric
+│     └── sublattices: tuple[Sublattice]   constituents, ratio
+├── parameters: tuple[Parameter]     kind, phase, constituents, order,
+│                                    expression, source_line
+├── functions: tuple[Function]       name, expression            (TDB)
+└── type_definitions: tuple[TypeDefinition]  symbol, kind, options (TDB)
+```
+
+Two design choices are worth calling out.
+
+**Parameter expressions are text, never evaluated.** `calphad-io` checks that an
+expression is well-formed enough to re-emit; it has no opinion about whether it
+is thermodynamically sensible. That is the solver's job.
+
+**`Database` is not the only record.** For DAT, the file's full structure — the
+per-endmember thermodynamic data options, P-T molar-volume terms, magnetic
+factors, QKTO chemical groups, MQMQA quadruplet coordinations — lives in a
+`DatLayout` under `db.header["layout"]`. The generic `Parameter` list is a
+*projection for inspection*, and the writer uses the layout. This is documented
+in `calphad_io.dat.layout`.
+
+## Validation
+
+`validate()` never raises. It returns `Finding` objects with a severity, a
+stable code, a message and structured detail:
+
+```
+ERROR   duplicate_phase                  [phase BCC_A2]
+        phase 'BCC_A2' is declared 2 times
+ERROR   undefined_constituent            [phase FCC_A1]
+        phase 'FCC_A1' references constituent 'XX', which is neither a
+        declared element nor a declared species
+WARNING element_mass_missing             [element CR]
+        element 'CR' has a mass of zero
+```
+
+Run `calphad-io validate --json` for the same findings as machine-readable data.
+
+The codes are: `duplicate_element`, `duplicate_phase`, `duplicate_parameter`,
+`duplicate_function`, `duplicate_type_definition`, `no_phases`, `no_elements`,
+`undefined_constituent`, `undefined_type_definition`, `unused_type_definition`,
+`parameter_for_undefined_phase`, `empty_parameter_expression`,
+`unbalanced_parentheses`, `constituent_count_mismatch`,
+`phase_without_constituents`, `parameter_sublattice_mismatch`,
+`suspicious_constituent_name`, `suspiciously_named_phase`,
+`element_mass_missing`, `phase_has_no_parameters`.
+
+## Limitations
+
+**Not supported at all:**
+
+* **`SUBI` (ionic two-sublattice)** — not read, not written. Affects
+  `FeMnCaS-1.dat`, which this library refuses with a clear
+  `UnsupportedFeatureError`. `pycalphad` cannot read it either (pycalphad#418).
+* **`IDVD` (real gas) and `IDWZ` (aqueous/Pitzer)** phase models.
+* **Heat-capacity thermodynamic data options** (7–12). These express an
+  endmember as heat-capacity coefficients rather than a Gibbs energy
+  polynomial. The reader rejects them explicitly rather than mis-reading them;
+  `pycalphad` raises `NotImplementedError` here too.
+* **Constant molar-volume options** (2, 5, 8, 11) and **P-T molar-volume
+  terms** are parsed but not interpreted.
+* **FactSage ≥ 8.1 DAT.** Out of scope by design; the format changed and 8.0-era
+  tools cannot read the new files (pycalphad#413).
+* **`DAT → TDB` and `TDB → DAT` conversion.** Refused, with an explanation of
+  exactly what would be lost. A TDB records no per-endmember thermodynamic data
+  option, no P-T molar-volume terms and no sublattice atom count; a DAT writer
+  needs all three. Guessing produces a file that looks right and computes the
+  wrong energy.
+
+**Known caveats:**
+
+* **No FactSage reference.** Correctness is evidenced by `pycalphad` reading the
+  output as identical (reproducible via [`scripts/verify.py`](scripts/verify.py))
+  and by bit-identical computed energies — *not* by FactSage accepting the file.
+  This is the same blocker the pycalphad maintainer named in 2022. It is reduced
+  but not eliminated, and the writer emits FactSage-8.0-style layout as
+  faithfully as the evidence allows.
+* **The validator still over-reports in a few DAT cases.** Constituent names in
+  DAT are arbitrary human-readable labels with no enforced grammar
+  (pycalphad#419), so a name that is neither an element nor a resolvable formula
+  is reported as `undefined_constituent` even when a solver would accept it.
+  Treat DAT `undefined_constituent` findings as *review this* rather than
+  *this is broken*.
+* **`duplicate_phase` for DAT is reported as `info`** when blocks differ, because
+  real databases (`Kaye_Pd-Ru-Tc-Mo.dat`, `PdRuTcMo.dat`) legitimately contain
+  several blocks with the same phase name.
+* **No thermodynamic evaluation**, no phase-diagram calculation, no model
+  fitting. This is an I/O library.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The test suite runs against **26 real databases** committed under `tests/data/`,
+sourced from `pycalphad` and `Thermochimica`. **25 of them round-trip cleanly**:
+the suite asserts, for every file this library can read, that a parse → write →
+re-parse cycle preserves the model, and that all 9 TDB files come back
+byte-for-byte. The 26th, `FeMnCaS-1.dat`, is refused by design rather than
+round-tripped — it uses the `SUBI` model (see Limitations). Deliberately
+corrupted copies under `tests/data/corrupt/` exercise the validator.
+
+## Prior art and credits
+
+Built on the format knowledge accumulated in
+[pycalphad](https://github.com/pycalphad/pycalphad) (Richard Otis, Brandon
+Bocklund and contributors), particularly `pycalphad/io/cs_dat.py` and
+`pycalphad/io/tdb.py`, and on the databases published by
+[Thermochimica](https://github.com/ORNL-CEES/thermochimica) (ORNL-CEES). The
+ChemSage `.DAT` layout was also cross-checked against OpenCalphad's unfinished
+`save_datformat` routine.
+
+## License
+
+MIT. See [LICENSE](LICENSE).