mat-data-handler 0.1.0__tar.gz

mat_data_handler-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Route data PRs to whoever reviews material parameter values;
+# route code PRs to whoever maintains the validation/export API.
+# Replace placeholders with actual GitHub usernames/teams before use.
+/packages/mat-data-handler-data/ @<materials-reviewer>
+/packages/mat-data-handler/      @<core-maintainer>

mat_data_handler-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What does this PR change?
+
+- [ ] New/updated material entry (data)
+- [ ] Schema change
+- [ ] Code change (validation, export, CLI)
+- [ ] Docs/CI only
+
+## Checklist
+
+- [ ] `pytest` passes locally for affected package(s)
+- [ ] For data changes: entry validates against `material.schema.json`
+- [ ] For schema changes: existing entries still validate, or migration notes are included
+- [ ] `CHANGELOG.md` updated for the affected package

mat_data_handler-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - name: Check out mat-data-handler
+        uses: actions/checkout@v4
+
+      - name: Check out mat-data (test fixture data)
+        uses: actions/checkout@v4
+        with:
+          repository: ICAMS/mat-data
+          # Pin to a released tag for reproducibility once available, e.g. ref: v2026.9.0
+          ref: main
+          path: mat-data-checkout
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install -e ".[test]"
+
+      - name: Validate mat-data entries
+        env:
+          MAT_DATA_LOCAL_PATH: ${{ github.workspace }}/mat-data-checkout
+        run: mat-build-database --output /tmp/materials.yaml --validate-only
+
+      - name: Rebuild database and check reproducibility
+        env:
+          MAT_DATA_LOCAL_PATH: ${{ github.workspace }}/mat-data-checkout
+        run: |
+          mat-build-database --output /tmp/materials.yaml
+          mat-build-database --output /tmp/materials.yaml --check
+
+      - name: Run tests
+        env:
+          MAT_DATA_LOCAL_PATH: ${{ github.workspace }}/mat-data-checkout
+        run: pytest -v
+
+      - name: Export a sample material
+        env:
+          MAT_DATA_LOCAL_PATH: ${{ github.workspace }}/mat-data-checkout
+        run: mat-extract-params copper_generic --outdir /tmp/includes

mat_data_handler-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write  # required for PyPI Trusted Publishing
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --outdir dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

mat_data_handler-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+*.egg
+.DS_Store

mat_data_handler-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# mat-data-handler
+
+## [0.1.0]
+
+- Initial release with CLI and API support.

mat_data_handler-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+This repository contains only code: validation, database-building, and
+Abaqus `.inc` export logic for material parameter sets. It has no material
+data of its own — that lives in the separate
+[mat-data](https://github.com/ICAMS/mat-data) repository.
+
+## Adding or updating a material (data change)
+
+Open a pull request against [mat-data](https://github.com/ICAMS/mat-data),
+not here. See its `CONTRIBUTING.md`.
+
+## Changing the API or export logic (code change)
+
+1. Make changes under `src/mat_data_handler/`.
+2. Add/update tests under `tests/`.
+3. Follow SemVer: patch for bug fixes, minor for backward-compatible
+   additions, major for breaking changes to the public API
+   (`build_database`, `export_entry`, CLI flags).
+4. Update `CHANGELOG.md`.
+
+## Running tests locally
+
+```bash
+pip install -e ".[test]"
+export MAT_DATA_LOCAL_PATH=../mat-data   # point at a sibling mat-data checkout
+pytest
+```
+
+## Reporting issues
+
+Please include the command run and the full error output. If the issue is
+about specific material values, file it against `mat-data` instead.

mat_data_handler-0.1.0/LICENSE

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

mat_data_handler-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: mat-data-handler
+Version: 0.1.0
+Summary: Validate, combine, and export crystal-plasticity material parameter sets for ICAMS CP-UMAT.
+Project-URL: Homepage, https://github.com/ICAMS/mat-data-handler
+Project-URL: Repository, https://github.com/ICAMS/mat-data-handler
+Author: ICAMS, Ruhr University Bochum
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: jsonschema>=4.18
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: referencing>=0.30
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mat-data-handler – Organizing Material Data for Crystal Plasticity
+
+Plain Python package to validate, combine, and export crystal-plasticity material parameter sets. The material data itself (YAML
+entries, JSON schemas, PROPS mapping table) is retrieved from the
+[mat-data](https://github.com/ICAMS/mat-data) repository and fetched over
+the network (and cached locally) at runtime.  
+Currently only support for the crystal plasticity model [ICAMS CP-UMAT](https://github.com/ICAMS/Crystal_Plasticity_UMAT.git) is provided. Use the `mat_extract_params` command to extract the require .inc files that contains the values for PROPS[9:] read by the ICAMS CP-UMAT.
+
+
+## Installation
+
+```bash
+pip install mat-data-handler
+```
+
+First use of the CLI/API fetches the pinned `mat-data` ref (default: `main`)
+and caches it under `~/.cache/mat-data-handler`. For offline use or local
+development against a sibling checkout, set:
+
+```bash
+export MAT_DATA_LOCAL_PATH=/path/to/mat-data   # skips network access entirely
+```
+
+Other environment variables: `MAT_DATA_REPO` (default `ICAMS/mat-data`),
+`MAT_DATA_REF` (default `main`; pin to a release tag for reproducibility),
+`MAT_DATA_FETCH_METHOD` (`http` default, stdlib-only tarball download; or
+`git`, which shells out to the `git` binary), `MAT_DATA_CACHE_DIR`.
+
+## API
+
+- `mat_data_handler.data_source.{entries_dir, schemas_dir, mapping_path}()` —
+  resolve (fetching/caching as needed) local paths to the `mat-data` content.
+- `mat_data_handler.database.build_database(entries, schemas, output_format="yaml")`
+  — validate all entries and return the combined database as text.
+- `mat_data_handler.database.validate_only(entries, schemas)` — validate only,
+  returns the number of valid materials.
+- `mat_data_handler.extract.export_entry(entry, mapping, schemas)` — export
+  one loaded material entry to Abaqus `PROPS` records.
+- `mat_data_handler.extract.load_document(path)` / `parse_mapping(path)` —
+  helpers to load a YAML/JSON entry or the `mapping.csv` table.
+
+## CLI
+
+```bash
+mat-build-database --output build/materials.yaml  # generate combined database
+mat-extract-params copper_generic --outdir build/includes
+mat-extract-params all --outdir build/includes
+```
+
+Both commands default to fetching data from `mat-data`; pass
+`--entries`/`--schemas`/`--mapping-file` to point at a different data source
+(e.g. a local checkout) directly.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). For adding/updating material data,
+see [mat-data](https://github.com/ICAMS/mat-data) instead — this repo has no
+data to edit.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+export MAT_DATA_LOCAL_PATH=../mat-data   # or wherever your mat-data checkout lives
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). (Material data in `mat-data` is licensed
+separately, under CC-BY-4.0.)

mat_data_handler-0.1.0/README.md

@@ -0,0 +1,71 @@
+# mat-data-handler – Organizing Material Data for Crystal Plasticity
+
+Plain Python package to validate, combine, and export crystal-plasticity material parameter sets. The material data itself (YAML
+entries, JSON schemas, PROPS mapping table) is retrieved from the
+[mat-data](https://github.com/ICAMS/mat-data) repository and fetched over
+the network (and cached locally) at runtime.  
+Currently only support for the crystal plasticity model [ICAMS CP-UMAT](https://github.com/ICAMS/Crystal_Plasticity_UMAT.git) is provided. Use the `mat_extract_params` command to extract the require .inc files that contains the values for PROPS[9:] read by the ICAMS CP-UMAT.
+
+
+## Installation
+
+```bash
+pip install mat-data-handler
+```
+
+First use of the CLI/API fetches the pinned `mat-data` ref (default: `main`)
+and caches it under `~/.cache/mat-data-handler`. For offline use or local
+development against a sibling checkout, set:
+
+```bash
+export MAT_DATA_LOCAL_PATH=/path/to/mat-data   # skips network access entirely
+```
+
+Other environment variables: `MAT_DATA_REPO` (default `ICAMS/mat-data`),
+`MAT_DATA_REF` (default `main`; pin to a release tag for reproducibility),
+`MAT_DATA_FETCH_METHOD` (`http` default, stdlib-only tarball download; or
+`git`, which shells out to the `git` binary), `MAT_DATA_CACHE_DIR`.
+
+## API
+
+- `mat_data_handler.data_source.{entries_dir, schemas_dir, mapping_path}()` —
+  resolve (fetching/caching as needed) local paths to the `mat-data` content.
+- `mat_data_handler.database.build_database(entries, schemas, output_format="yaml")`
+  — validate all entries and return the combined database as text.
+- `mat_data_handler.database.validate_only(entries, schemas)` — validate only,
+  returns the number of valid materials.
+- `mat_data_handler.extract.export_entry(entry, mapping, schemas)` — export
+  one loaded material entry to Abaqus `PROPS` records.
+- `mat_data_handler.extract.load_document(path)` / `parse_mapping(path)` —
+  helpers to load a YAML/JSON entry or the `mapping.csv` table.
+
+## CLI
+
+```bash
+mat-build-database --output build/materials.yaml  # generate combined database
+mat-extract-params copper_generic --outdir build/includes
+mat-extract-params all --outdir build/includes
+```
+
+Both commands default to fetching data from `mat-data`; pass
+`--entries`/`--schemas`/`--mapping-file` to point at a different data source
+(e.g. a local checkout) directly.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). For adding/updating material data,
+see [mat-data](https://github.com/ICAMS/mat-data) instead — this repo has no
+data to edit.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+export MAT_DATA_LOCAL_PATH=../mat-data   # or wherever your mat-data checkout lives
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). (Material data in `mat-data` is licensed
+separately, under CC-BY-4.0.)

mat_data_handler-0.1.0/conda-recipe/meta.yaml

@@ -0,0 +1,49 @@
+{% set name = "mat-data-handler" %}
+{% set version = "0.1.0" %}
+
+package:
+  name: {{ name|lower }}
+  version: {{ version }}
+
+source:
+  url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/{{ name }}-{{ version }}.tar.gz
+  # sha256: <fill in after the first PyPI release>
+
+build:
+  number: 0
+  noarch: python
+  script: {{ PYTHON }} -m pip install . -vv
+  entry_points:
+    - mat-build-database = mat_data_handler.database:main
+    - mat-extract-params = mat_data_handler.extract:main
+
+requirements:
+  host:
+    - python >=3.9
+    - pip
+    - hatchling
+  run:
+    - python >=3.9
+    - pyyaml >=6.0
+    - jsonschema >=4.18
+    - referencing >=0.30
+# Note: no data dependency here. mat-data-handler fetches material data from
+# https://github.com/ICAMS/mat-data over the network at runtime (or from
+# MAT_DATA_LOCAL_PATH), rather than depending on a packaged data distribution.
+
+test:
+  imports:
+    - mat_data_handler
+  commands:
+    - mat-build-database --help
+    - mat-extract-params --help
+
+about:
+  home: https://github.com/ICAMS/mat-data-handler
+  license: MIT
+  license_file: LICENSE
+  summary: Validate, combine, and export crystal-plasticity material parameter sets for Abaqus UMATs.
+
+extra:
+  recipe-maintainers:
+    - <github-username>

mat_data_handler-0.1.0/environment.yml

@@ -0,0 +1,13 @@
+name: mat-data-handler
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python >=3.9
+  - pyyaml >=6.0
+  - jsonschema >=4.18
+  - referencing >=0.30
+  - pytest
+  - pip
+  - pip:
+      - -e .

mat_data_handler-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mat-data-handler"
+version = "0.1.0"
+description = "Validate, combine, and export crystal-plasticity material parameter sets for ICAMS CP-UMAT."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "ICAMS, Ruhr University Bochum" }]
+dependencies = [
+  "PyYAML>=6.0",
+  "jsonschema>=4.18",
+  "referencing>=0.30",
+]
+# Note: material data is NOT a pip/conda dependency. It is fetched at runtime
+# from the separate https://github.com/ICAMS/mat-data repository and cached
+# locally; see mat_data_handler.data_source. Requires network access on first
+# use (or MAT_DATA_LOCAL_PATH pointing at a local checkout for offline use).
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.scripts]
+mat-build-database = "mat_data_handler.database:main"
+mat-extract-params = "mat_data_handler.extract:main"
+
+[project.urls]
+Homepage = "https://github.com/ICAMS/mat-data-handler"
+Repository = "https://github.com/ICAMS/mat-data-handler"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mat_data_handler"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mat_data_handler-0.1.0/src/mat_data_handler/__init__.py

@@ -0,0 +1,18 @@
+"""Public API: validate/combine material YAML entries and export Abaqus .inc files.
+
+See :mod:`mat_data_handler.database` for building the combined database and
+:mod:`mat_data_handler.extract` for exporting selected materials to Abaqus
+``PROPS`` include files.
+"""
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("mat-data-handler")
+except metadata.PackageNotFoundError:  # local checkout, not installed
+    __version__ = "0.0.0+dev"
+
+from .database import build_database, collect, validate_only
+from .extract import export_material
+
+__all__ = ["build_database", "collect", "validate_only", "export_material", "__version__"]

mat_data_handler-0.1.0/src/mat_data_handler/data_source.py

@@ -0,0 +1,89 @@
+"""Resolve the mat-data material dataset over the network (no pip/conda dependency).
+
+The material entries, JSON schemas, and PROPS mapping table live in the
+separate `mat-data` repository (https://github.com/ICAMS/mat-data), not as an
+installable package. This module fetches (and caches) that repository's
+content, or uses a local checkout directly during development.
+
+Resolution order:
+1. ``MAT_DATA_LOCAL_PATH`` env var, if set: use that directory as-is (no
+   network access). Intended for local development against a sibling
+   checkout of ``mat-data``, and for CI, which checks out ``mat-data``
+   itself and points this at it.
+2. Cached download for the requested ref under ``MAT_DATA_CACHE_DIR``
+   (defaults to ``~/.cache/mat-data-handler``).
+3. Fresh download via ``MAT_DATA_FETCH_METHOD`` (``http`` tarball download by
+   default, stdlib-only; or ``git clone`` if explicitly requested).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tarfile
+import urllib.request
+from pathlib import Path
+
+DEFAULT_REPO = "ICAMS/mat-data"
+DEFAULT_REF = "main"
+
+
+def _cache_dir() -> Path:
+    return Path(os.environ.get("MAT_DATA_CACHE_DIR", Path.home() / ".cache" / "mat-data-handler"))
+
+
+def _fetch_http(repo: str, ref: str, dest: Path) -> None:
+    """Download and extract the repo's tarball for ``ref`` via GitHub's codeload API."""
+    url = f"https://codeload.github.com/{repo}/tar.gz/{ref}"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    archive = dest.parent / f"{dest.name}.tar.gz"
+    with urllib.request.urlopen(url) as response, open(archive, "wb") as stream:
+        stream.write(response.read())
+    try:
+        with tarfile.open(archive) as tar:
+            # GitHub tarballs contain a single top-level "<repo>-<ref>/" directory.
+            members = tar.getmembers()
+            top = os.path.commonpath([m.name for m in members])
+            safe_members = [m for m in members if not (m.name.startswith("/") or ".." in Path(m.name).parts)]
+            tar.extractall(dest.parent, members=safe_members)  # noqa: S202 -- paths sanitized above
+        (dest.parent / top).replace(dest)
+    finally:
+        archive.unlink(missing_ok=True)
+
+
+def _fetch_git(repo: str, ref: str, dest: Path) -> None:
+    """Shallow-clone the repo at ``ref`` (branch or tag) using the system ``git`` binary."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["git", "clone", "--depth", "1", "--branch", ref, f"https://github.com/{repo}.git", str(dest)],
+        check=True,
+    )
+
+
+def data_root(repo: str = None, ref: str = None) -> Path:
+    """Return a local directory containing entries/, schemas/, mapping_icams_cp.csv."""
+    local = os.environ.get("MAT_DATA_LOCAL_PATH")
+    if local:
+        return Path(local)
+
+    repo = repo or os.environ.get("MAT_DATA_REPO", DEFAULT_REPO)
+    ref = ref or os.environ.get("MAT_DATA_REF", DEFAULT_REF)
+    method = os.environ.get("MAT_DATA_FETCH_METHOD", "http")
+
+    dest = _cache_dir() / repo.replace("/", "__") / ref
+    if not dest.is_dir():
+        fetch = _fetch_git if method == "git" else _fetch_http
+        fetch(repo, ref, dest)
+    return dest
+
+
+def entries_dir(repo: str = None, ref: str = None) -> Path:
+    return data_root(repo, ref) / "entries"
+
+
+def schemas_dir(repo: str = None, ref: str = None) -> Path:
+    return data_root(repo, ref) / "schemas"
+
+
+def mapping_path(repo: str = None, ref: str = None) -> Path:
+    return data_root(repo, ref) / "mapping_icams_cp.csv"

mat_data_handler-0.1.0/src/mat_data_handler/database.py

@@ -0,0 +1,211 @@
+"""Validate individual materials offline and atomically build a collection.
+
+Ported from the ``cp-work`` proof of concept (materials/build_database.py),
+adapted to load default data from the installable ``mat-data-handler-data``
+package instead of a fixed repo-relative ``ROOT``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+
+import yaml
+from jsonschema import Draft201909Validator
+from referencing import Registry, Resource
+
+PLASTIC_MODELS = ("ICAMS CP-UMAT", "DAMASK phenopowerlaw")
+
+
+class EntryLoader(yaml.SafeLoader):
+    def compose_node(self, parent, index):
+        if self.check_event(yaml.AliasEvent):
+            raise ValueError("YAML aliases are not allowed")
+        return super().compose_node(parent, index)
+
+    def construct_mapping(self, node, deep=False):
+        result = {}
+        for key_node, value_node in node.value:
+            key = self.construct_object(key_node, deep=deep)
+            if not isinstance(key, str):
+                raise ValueError(f"line {key_node.start_mark.line + 1}: mapping keys must be strings")
+            if key in result:
+                raise ValueError(f"line {key_node.start_mark.line + 1}: duplicate key {key!r}")
+            result[key] = self.construct_object(value_node, deep=deep)
+        return result
+
+
+def json_errors(value, path="$"):
+    """Reject YAML-only values and non-finite numbers before schema validation."""
+    if isinstance(value, dict):
+        for key, child in value.items():
+            yield from json_errors(child, f"{path}.{key}")
+    elif isinstance(value, list):
+        for index, child in enumerate(value):
+            yield from json_errors(child, f"{path}[{index}]")
+    elif isinstance(value, float) and not math.isfinite(value):
+        yield f"{path}: number must be finite"
+    elif value is not None and type(value) not in (str, int, float, bool):
+        yield f"{path}: unsupported YAML value ({type(value).__name__}); quote text identifiers"
+
+
+def validator(schema_dir: Path) -> Draft201909Validator:
+    resources = []
+    for path in sorted(Path(schema_dir).glob("*.json")):
+        schema = json.loads(path.read_text(encoding="utf-8"))
+        Draft201909Validator.check_schema(schema)
+        resources.append((path.resolve().as_uri(), Resource.from_contents(schema)))
+    # Registry has no retrieval callback: unresolved references cannot use the network.
+    registry = Registry().with_resources(resources)
+    uri = (Path(schema_dir) / "material_schema.json").resolve().as_uri()
+    return Draft201909Validator({"$ref": uri}, registry=registry)
+
+
+def schema_messages(error):
+    if error.validator == "oneOf" and error.context:
+        # Select only diagnostics from the named model's branch. Validation
+        # still runs against the complete schema, including shared constraints.
+        if isinstance(error.instance, dict):
+            model = error.instance.get("plastic_model_name")
+            matching = [
+                index for index, branch in enumerate(error.validator_value)
+                if branch.get("properties", {}).get("plastic_model_name", {}).get("const") == model
+                and model in PLASTIC_MODELS
+            ]
+            if len(matching) == 1:
+                for child in error.context:
+                    if child.schema_path and child.schema_path[0] == matching[0]:
+                        yield from schema_messages(child)
+                return
+        yield f"{error.json_path}: does not match an allowed schema alternative"
+        for child in error.context:
+            yield from schema_messages(child)
+    else:
+        yield f"{error.json_path}: {error.message}"
+
+
+def collect(entries: Path, schemas: Path):
+    """Validate every YAML entry in ``entries`` against ``schemas``.
+
+    Returns ``(database, errors)``. ``database`` maps material key (filename
+    stem) to the parsed entry; ``errors`` lists human-readable problems.
+    """
+    entries, schemas = Path(entries), Path(schemas)
+    check = validator(schemas)
+    files = sorted(p for p in entries.iterdir() if p.is_file() and p.suffix in (".yaml", ".yml"))
+    if not files:
+        raise ValueError(f"{entries}: no YAML entries found")
+    database, errors = {}, []
+    for path in files:
+        if not re.fullmatch(r"[a-z0-9_]+", path.stem):
+            errors.append(f"{path}: filename stem must contain lowercase letters, digits, or underscores")
+            continue
+        if path.stem in database:
+            errors.append(f"{path}: duplicate material key {path.stem!r}")
+            continue
+        try:
+            entry = yaml.load(path.read_text(encoding="utf-8"), Loader=EntryLoader)
+            problems = list(json_errors(entry))
+            if not problems and isinstance(entry, dict):
+                model_object = entry.get("constitutive_model", {})
+                if isinstance(model_object, dict):
+                    model = model_object.get("plastic_model_name")
+                    if model not in PLASTIC_MODELS:
+                        problems = [
+                            "$.constitutive_model.plastic_model_name: "
+                            f"missing or unsupported plastic model name {model!r}; "
+                            f"expected one of {PLASTIC_MODELS!r}"
+                        ]
+            if not problems:
+                problems = [
+                    message
+                    for error in check.iter_errors(entry)
+                    for message in schema_messages(error)
+                ]
+            errors.extend(f"{path}: {problem}" for problem in problems)
+            database[path.stem] = entry
+        except (ValueError, yaml.YAMLError) as error:
+            errors.append(f"{path}: {error}")
+    return database, errors
+
+
+def validate_only(entries: Path, schemas: Path) -> int:
+    """Validate entries and return the count of valid materials, raising on error."""
+    database, errors = collect(entries, schemas)
+    if errors:
+        raise ValueError("\n".join(errors))
+    return len(database)
+
+
+def build_database(entries: Path, schemas: Path, output_format: str = "yaml") -> str:
+    """Validate entries and return the serialized combined database as text."""
+    database, errors = collect(entries, schemas)
+    if errors:
+        raise ValueError("\n".join(errors))
+    if output_format == "json":
+        return json.dumps(database, indent=2, sort_keys=True, ensure_ascii=False, allow_nan=False) + "\n"
+    return yaml.safe_dump(database, sort_keys=True, allow_unicode=True)
+
+
+def main(argv=None):
+    from .data_source import entries_dir as default_entries_dir
+    from .data_source import schemas_dir as default_schemas_dir
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--entries", type=Path, help="Defaults to the mat-data repo's entries/ (fetched/cached)")
+    parser.add_argument("--schemas", type=Path, help="Defaults to the mat-data repo's schemas/ (fetched/cached)")
+    parser.add_argument("--output", "-o", type=Path, required=True, help="Destination (.yaml/.yml or .json)")
+    parser.add_argument("--format", choices=("yaml", "json"), help="Defaults to output extension, or YAML")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--check", action="store_true", help="Fail if the output is missing or stale; write nothing")
+    mode.add_argument("--validate-only", action="store_true", help="Validate entries without building")
+    args = parser.parse_args(argv)
+    try:
+        entries = args.entries or default_entries_dir()
+        schemas = args.schemas or default_schemas_dir()
+
+        output = args.output
+        output_format = args.format or ("json" if output.suffix == ".json" else "yaml")
+        if output.resolve().parent in (Path(entries).resolve(), Path(schemas).resolve()):
+            raise ValueError("Output must be outside the entries and schemas directories")
+
+        if args.validate_only:
+            count = validate_only(entries, schemas)
+            print(f"Validated {count} materials")
+            return 0
+
+        content = build_database(entries, schemas, output_format)
+        data = content.encode("utf-8")
+        if args.check:
+            if not output.is_file() or output.read_bytes() != data:
+                print(f"{output}: missing or stale; rebuild without --check", file=sys.stderr)
+                return 1
+            print(f"{output}: up to date")
+            return 0
+        output.parent.mkdir(parents=True, exist_ok=True)
+        temporary = None
+        try:
+            with tempfile.NamedTemporaryFile(dir=output.parent, delete=False) as stream:
+                temporary = Path(stream.name)
+                stream.write(data)
+                stream.flush()
+                os.fsync(stream.fileno())
+            temporary.replace(output)
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)
+        print(f"Wrote database to {output}")
+        return 0
+    except Exception as error:
+        print(f"Build failed: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mat_data_handler-0.1.0/src/mat_data_handler/extract.py

@@ -0,0 +1,315 @@
+"""Export schema-valid material entries to shared Abaqus PROPS(9:) include files.
+
+Ported from ``cp-work``'s ``materials/extract_params.py``. Business logic for
+which parameters are active and how they map to Abaqus PROPS positions is
+unchanged; only default data locations moved to the ``mat-data-handler-data``
+package.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import csv
+import io
+import json
+import math
+from pathlib import Path
+import re
+import sys
+
+import yaml
+
+from .database import EntryLoader, json_errors, schema_messages, validator
+
+FLAG_LAYOUT = dict(zip((
+    "flag_isotropic_hardening", "flag_back_stress", "flag_gradient_plasticity",
+    "flag_int", "flag_super_alloy", "flag_trip", "flag_thermal",
+), range(7)))
+BASE = ["C11", "C12", "C44", "number_slip_systems", "reference_shear_rate",
+        "stress_exponent", "initial_critical_resolved_shear_stress"]
+ISO = ["saturated_slip_resistance", "reference_hardening_rate", "self_hardening",
+       "cross_hardening", "hardening_exponent"]
+KIN = ["nslip_kinematic_hardening", "kinematic_hardening_a1", "kinematic_hardening_b1",
+       "ohno_wang_exponent", "chaboche_parameter_a2", "chaboche_parameter_b2",
+       "chaboche_parameter_a3", "chaboche_parameter_b3"]
+GRAD = ["flag_octree", "C_taui", "L_size", "I_gnd_iso", "I_gnd_kin", "C_unit", "B_lattice"]
+THERM = ["activation_energy", "c11_tcoeff", "c12_tcoeff", "c44_tcoeff",
+         "kinematic_hardening_a1_tcoeff", "crss0_coef_tcoeff"]
+
+
+def load_document(path: Path):
+    def unique_object(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError(f"duplicate key: {key}")
+            result[key] = value
+        return result
+
+    path = Path(path)
+    text = path.read_text(encoding="utf-8")
+    # JSON's exponent syntax (e.g. 1e-06) differs from PyYAML's resolver.
+    value = (json.loads(text, object_pairs_hook=unique_object) if path.suffix.lower() == ".json"
+             else yaml.load(text, Loader=EntryLoader))
+    errors = list(json_errors(value))
+    if errors:
+        raise ValueError("; ".join(errors))
+    return value
+
+
+def parse_mapping(path: Path):
+    with Path(path).open(encoding="utf-8-sig", newline="") as stream:
+        rows = [{k.strip(): v.strip() for k, v in row.items()} for row in csv.DictReader(stream, delimiter=";")]
+    result = {}
+    for row in rows:
+        key = row[next(k for k in row if k.startswith("json_key"))]
+        if key in result:
+            raise ValueError(f"duplicate mapping key: {key}")
+        result[key] = row
+    return result
+
+
+def condition(expression, env, provided=False):
+    expression = expression.strip()
+    if expression in ("always", ""):
+        return True
+    if expression == "never":
+        return False
+    if expression == "provided":
+        return provided
+    node = ast.parse(expression, mode="eval")
+    allowed = (ast.Expression, ast.Compare, ast.Name, ast.Load, ast.Constant,
+               ast.Eq, ast.NotEq, ast.Gt, ast.GtE, ast.Lt, ast.LtE,
+               ast.BoolOp, ast.And, ast.Or, ast.UnaryOp, ast.Not)
+    if any(not isinstance(n, allowed) for n in ast.walk(node)):
+        raise ValueError(f"unsupported mapping condition: {expression}")
+    return bool(eval(compile(node, "<mapping condition>", "eval"), {"__builtins__": {}}, env))
+
+
+def scalar(value, key):
+    while isinstance(value, list):
+        if len(value) != 1:
+            raise ValueError(f"{key}: current Fortran reader supports only one family / coefficient")
+        value = value[0]
+    if isinstance(value, bool) or not isinstance(value, (float, int)) or not math.isfinite(value):
+        raise ValueError(f"{key}: expected a finite number")
+    return value
+
+
+def export_entry(entry, mapping, schemas: Path):
+    model = entry.get("constitutive_model", {}) if isinstance(entry, dict) else {}
+    if not isinstance(model, dict) or model.get("plastic_model_name") != "ICAMS CP-UMAT":
+        raise ValueError("CP-UMAT export requires plastic_model_name: ICAMS CP-UMAT")
+    errors = [m for e in validator(schemas).iter_errors(entry) for m in schema_messages(e)]
+    if errors:
+        raise ValueError("\n".join(errors))
+    plastic = model["plastic_parameters"]
+    elastic = model["elastic_parameters"]
+    units = model["units"]
+    records, notes = [], []
+
+    def raw(key):
+        if key == "space_group_number":
+            if key in plastic and plastic[key] != entry[key]:
+                raise ValueError("conflicting space_group_number values")
+            return entry[key]
+        return elastic.get(key) if key in elastic else plastic.get(key)
+
+    flags = {}
+    packed = plastic.get("super_flag")
+    if packed is not None and not 0 <= packed <= 0x7FFFFFFF:
+        raise ValueError("super_flag exceeds signed 32-bit range")
+    for key, pos in FLAG_LAYOUT.items():
+        if key in plastic:
+            flags[key] = plastic[key]
+            if packed is not None and ((packed >> (4 * pos)) & 15) != flags[key]:
+                raise ValueError(f"super_flag mismatch for {key}")
+        elif packed is not None:
+            flags[key] = (packed >> (4 * pos)) & 15
+            notes.append(f"{key}: decoded from super_flag = {flags[key]}")
+        else:
+            flags[key] = int(mapping[key]["default_value"])
+            notes.append(f"{key}: mapping default = {flags[key]}")
+        maximum = 3 if key == "flag_back_stress" else 1
+        if not 0 <= flags[key] <= maximum:
+            raise ValueError(f"{key}: unsupported mode {flags[key]}")
+    super_flag = sum(value << (4 * FLAG_LAYOUT[key]) for key, value in flags.items())
+    if packed is not None and packed != super_flag:
+        raise ValueError("super_flag contains unsupported spare bits")
+    env = dict(zip(("iso_mode", "kin_mode", "grad_mode", "int_mode", "super_mode", "trip_mode", "thermal_mode"), flags.values()))
+    if env["super_mode"]:
+        raise ValueError("superalloy export unavailable: the schema/mapping do not represent all 12 values read by the UMAT")
+    if env["trip_mode"] or env["int_mode"]:
+        raise ValueError("TRIP/internal-stress export requires additional constitutive compatibility checks; currently unsupported")
+    if scalar(plastic.get("number_slip_families", 1), "number_slip_families") != 1:
+        raise ValueError("current Fortran reader supports one slip family only")
+    if any(key in elastic for key in ("C33", "C66", "C13")):
+        raise ValueError("current Fortran reader consumes only C11, C12, C44; additional elastic constants cannot be exported")
+    for key, value in plastic.items():
+        if isinstance(value, list):
+            scalar(value, key)
+    if env["thermal_mode"]:
+        if plastic.get("temperature_polynomial_degree", 1) != 1:
+            raise ValueError("current Fortran reader supports linear thermal slopes only")
+        extra = [k for k in plastic if k.endswith("_tcoeff") and k not in THERM]
+        if extra:
+            raise ValueError(f"thermal coefficients not read by CP-UMAT: {extra}")
+
+    def append(key, value, source, unit="-"):
+        records.append(dict(props_position=9 + len(records), key=key, value=value, source=source, unit=unit))
+
+    def mapped(key):
+        row = mapping[key]
+        value = raw(key)
+        provided = value is not None
+        if not condition(row["active_if"], env, provided):
+            raise ValueError(f"mapping disables {key}, but the Fortran reader requires its slot")
+        source = "entry"
+        if not provided:
+            if condition(row["required_if"], env, provided):
+                raise ValueError(f"missing required active parameter: {key}")
+            value = float(row["default_value"].replace(",", "."))
+            source = "mapping default"
+        value = scalar(value, key)
+        if row["fortran_type"].startswith("integer"):
+            if value != int(value):
+                raise ValueError(f"{key}: expected integer")
+            value = int(value)
+        elif not row["fortran_type"].startswith("real"):
+            raise ValueError(f"{key}: unsupported mapping type")
+        if key in ("number_slip_systems", "nslip_kinematic_hardening") and not 1 <= value <= 60:
+            raise ValueError(f"{key}: must be within current Nslp_mx=60")
+        if key in ("I_gnd_iso", "I_gnd_kin") and value not in (0, 1):
+            raise ValueError(f"{key}: expected 0 or 1")
+        unit = row["unit"]
+        if provided and unit.startswith("MPa"):
+            category = "Stiffness" if key in elastic or key in ("c11_tcoeff", "c12_tcoeff", "c44_tcoeff") else "Stress"
+            if units[category] == "Pa":
+                value *= 1e-6
+                source += " (Pa converted to MPa)"
+        if source == "mapping default":
+            notes.append(f"{key}: mapping default = {value} {unit}")
+        append(key, value, source, unit)
+
+    mapped("space_group_number")
+    append("super_flag", super_flag, "packed flags")
+    for key in BASE:
+        mapped(key)
+    if env["iso_mode"]:
+        for key in ISO:
+            mapped(key)
+    if env["kin_mode"]:
+        for key in KIN:
+            mapped(key)
+    if env["grad_mode"]:
+        for key in GRAD:
+            mapped(key)
+        # Not yet in mapping/schema; retain the explicit reader initialization.
+        append("CD_smooth", 3e-15, "src/mod_material.f default")
+        notes.append("CD_smooth: reader default = 3e-15 (not configurable in current schema/mapping)")
+    if env["thermal_mode"]:
+        for key in THERM:
+            mapped(key)
+    return records, notes
+
+
+def render_outputs(name, entry, records, notes, source):
+    values = [str(r["value"]) if isinstance(r["value"], int) else format(r["value"], ".17g") for r in records]
+    inc_name = f"{name}_inp_{len(values)}p.inc"
+    lines = [", ".join(values[i:i + 8]) + ("," if i + 8 < len(values) else "") for i in range(0, len(values), 8)]
+    stream = io.StringIO()
+    writer = csv.DictWriter(stream, fieldnames=list(records[0]))
+    writer.writeheader()
+    writer.writerows(records)
+    manifest = [f"Source: {source}", f"Include: {inc_name}", f"Include count: {len(values)}",
+                f"Total Abaqus constant count: {len(values) + 8}",
+                "PROPS(1:8) supplied by caller: material selector, three Euler angles (rad), four spare values.",
+                "", "Abaqus usage (replace Euler angles for each grain):",
+                f"*User Material, constants={len(values) + 8}",
+                f'{entry["material_id"]}, 0., 0., 0., 0., 0., 0., 0.,',
+                f"*Include, input={inc_name}", "", "Positions:"]
+    manifest += [f'PROPS({r["props_position"]}): {r["key"]} = {r["value"]} [{r["unit"]}] ({r["source"]})' for r in records]
+    manifest += ["", "Defaults and notes:", *notes]
+    return {inc_name: "\n".join(lines) + "\n", f"{name}_props_flat.csv": stream.getvalue(),
+            f"{name}_props_manifest.txt": "\n".join(manifest) + "\n"}
+
+
+def export_material(name: str, entry, mapping, schemas: Path):
+    """Export one already-loaded material entry. Returns ``(records, notes)``."""
+    return export_entry(entry, mapping, schemas)
+
+
+def _default_data_paths():
+    from .data_source import entries_dir, mapping_path, schemas_dir
+
+    return entries_dir(), schemas_dir(), mapping_path()
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("material", help="Material key or 'all'")
+    parser.add_argument("--input", "--yaml_file", "--json_file", dest="input", type=Path,
+                         help="Entry directory, single entry, or combined YAML/JSON database; "
+                              "defaults to the mat-data repo's entries/ (fetched/cached)")
+    parser.add_argument("--mapping-file", "--mapping_file", dest="mapping_file", type=Path,
+                         help="Defaults to the mat-data repo's mapping.csv (fetched/cached)")
+    parser.add_argument("--schemas", type=Path, help="Defaults to the mat-data repo's schemas/ (fetched/cached)")
+    parser.add_argument("--outdir", type=Path, default=Path("."))
+    parser.add_argument("--values-per-line", type=int, choices=[8], default=8)
+    args = parser.parse_args(argv)
+    try:
+        if args.input is None or args.mapping_file is None or args.schemas is None:
+            default_entries, default_schemas, default_mapping = _default_data_paths()
+            input_path = args.input or default_entries
+            mapping_file = args.mapping_file or default_mapping
+            schemas = args.schemas or default_schemas
+        else:
+            input_path, mapping_file, schemas = args.input, args.mapping_file, args.schemas
+
+        mapping = parse_mapping(mapping_file)
+        input_path = Path(input_path)
+        if input_path.is_dir():
+            files = sorted(p for p in input_path.iterdir() if p.suffix in (".yaml", ".yml") and p.is_file())
+            selected = files if args.material == "all" else [p for p in files if p.stem == args.material]
+            entries = {}
+            for path in selected:
+                if path.stem in entries:
+                    raise ValueError(f"duplicate material key: {path.stem}")
+                entries[path.stem] = load_document(path)
+        else:
+            data = load_document(input_path)
+            if not isinstance(data, dict):
+                raise ValueError("input must be a material object or keyed database")
+            entries = {input_path.stem: data} if "constitutive_model" in data else data
+            if args.material != "all":
+                entries = {k: v for k, v in entries.items() if k == args.material}
+        if not entries:
+            raise ValueError(f"no matching materials: {args.material}")
+
+        outputs, errors = {}, []
+        for name, entry in sorted(entries.items()):
+            try:
+                if not isinstance(name, str) or not re.fullmatch("[a-z0-9_]+", name):
+                    raise ValueError("invalid material key")
+                records, notes = export_entry(entry, mapping, schemas)
+                outputs.update(render_outputs(name, entry, records, notes, input_path))
+            except (ValueError, KeyError) as error:
+                errors.append(f"{name}: {error}")
+        if errors:
+            raise ValueError("\n".join(errors))
+
+        # Validate the whole selection before touching any output files.
+        args.outdir.mkdir(parents=True, exist_ok=True)
+        for name, content in outputs.items():
+            path = args.outdir / name
+            path.write_text(content, encoding="utf-8")
+            print(f"Wrote {path}")
+        return 0
+    except Exception as error:
+        print(f"Export failed: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mat_data_handler-0.1.0/tests/conftest.py

@@ -0,0 +1,22 @@
+"""Point tests at a local mat-data checkout instead of fetching over the network.
+
+Assumes the sibling layout used during development:
+``~/Codes/mat-data-handler`` and ``~/Codes/mat-data``. CI instead sets
+``MAT_DATA_LOCAL_PATH`` itself after checking out the ``mat-data`` repo.
+"""
+
+import os
+from pathlib import Path
+
+import pytest
+
+_SIBLING_MAT_DATA = Path(__file__).resolve().parents[3] / "mat-data"
+
+
+@pytest.fixture(autouse=True, scope="session")
+def _mat_data_local_path():
+    if "MAT_DATA_LOCAL_PATH" not in os.environ and _SIBLING_MAT_DATA.is_dir():
+        os.environ["MAT_DATA_LOCAL_PATH"] = str(_SIBLING_MAT_DATA)
+    if "MAT_DATA_LOCAL_PATH" not in os.environ:
+        pytest.skip("MAT_DATA_LOCAL_PATH not set and no sibling mat-data checkout found")
+    yield

mat_data_handler-0.1.0/tests/test_database.py

@@ -0,0 +1,7 @@
+from mat_data_handler.data_source import entries_dir, schemas_dir
+from mat_data_handler.database import validate_only
+
+
+def test_bundled_entries_validate():
+    count = validate_only(entries_dir(), schemas_dir())
+    assert count >= 1

mat_data_handler-0.1.0/tests/test_extract.py

@@ -0,0 +1,10 @@
+from mat_data_handler.data_source import entries_dir, mapping_path, schemas_dir
+from mat_data_handler.extract import export_entry, load_document, parse_mapping
+
+
+def test_export_copper():
+    entry = load_document(entries_dir() / "copper_generic.yaml")
+    mapping = parse_mapping(mapping_path())
+    records, notes = export_entry(entry, mapping, schemas_dir())
+    assert records[0]["props_position"] == 9
+    assert any(r["key"] == "C11" for r in records)