ANYmaterial 0.1.0__py3-none-any.whl

anymaterial/__init__.py

@@ -0,0 +1,135 @@
+"""Structural material models for finite-element analysis.
+
+The package owns material behaviour and nothing else: elastic symmetry and
+compliance, the reductions a shell or beam formulation needs, nonlinear
+hardening curves, directional yield criteria, and a serializable
+specification.  Meshes, sections and solvers live elsewhere.
+
+Elastic compliance uses engineering Voigt order ``[11, 22, 33, 23, 13, 12]``:
+
+``[eps11, eps22, eps33, gamma23, gamma13, gamma12] = S @
+  [sig11, sig22, sig33, tau23, tau13, tau12]``
+
+This ordering is the family-wide convention.  It is stated here because this
+package defines it, and every consumer is expected to match it rather than
+transposing at the boundary.
+
+The package deliberately does not import ANYsolver.  Materials are described
+here and consumed there, never the other way round, so the dependency stays
+acyclic and a material can be validated without a solver present.
+
+``anymaterial.gui`` is not imported here, so importing the package never
+requires a display or a tkinter build.
+"""
+
+from __future__ import annotations
+
+from .contract import (
+    ENGINEERING_VOIGT_ORDER,
+    SUPPORTED_ELASTIC_SYMMETRIES,
+    StructuralMaterial,
+    elastic_compliance_matrix,
+    is_isotropic_material,
+    is_orthotropic_material,
+    material_symmetry,
+)
+from .curves import (
+    DNVC208MaterialCurve,
+    HardeningCurve,
+    LinearHardeningCurve,
+    PiecewiseLinearCurve,
+    PowerLawHardeningCurve,
+    curve_from_properties,
+)
+from .isotropic import IsotropicMaterial
+from .library import (
+    STEEL_DENSITY,
+    STEEL_POISSON_RATIO,
+    LibraryEntry,
+    MaterialLibrary,
+    add_to_user_library,
+    available_grades,
+    builtin_library,
+    dnv_c208_steel_curve,
+    dnv_c208_steel_properties,
+    library,
+    steel,
+    thickness_classes,
+    user_library_path,
+)
+from .plot import CurveSeries, curve_svg, sample_curve, write_curve_svg
+from .orthotropic import OrthotropicMaterial
+from .reductions import (
+    BeamMaterialProperties,
+    beam_material_properties,
+    shell_characteristic_modulus,
+    shell_material_matrices,
+)
+from .spec import (
+    MaterialSpec,
+    build_hardening_curve,
+    hardening_descriptor,
+    load_specs,
+    save_specs,
+    spec_from_material,
+)
+from .validation import material_validation_errors, validate_material
+from .yield_criteria import (
+    Hill48Yield,
+    hill48_coefficients,
+    hill48_equivalent_stress,
+    hill48_strengths,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BeamMaterialProperties",
+    "CurveSeries",
+    "DNVC208MaterialCurve",
+    "ENGINEERING_VOIGT_ORDER",
+    "HardeningCurve",
+    "Hill48Yield",
+    "IsotropicMaterial",
+    "LibraryEntry",
+    "LinearHardeningCurve",
+    "MaterialLibrary",
+    "MaterialSpec",
+    "OrthotropicMaterial",
+    "PiecewiseLinearCurve",
+    "PowerLawHardeningCurve",
+    "STEEL_DENSITY",
+    "STEEL_POISSON_RATIO",
+    "SUPPORTED_ELASTIC_SYMMETRIES",
+    "StructuralMaterial",
+    "add_to_user_library",
+    "available_grades",
+    "beam_material_properties",
+    "build_hardening_curve",
+    "builtin_library",
+    "curve_from_properties",
+    "curve_svg",
+    "dnv_c208_steel_curve",
+    "dnv_c208_steel_properties",
+    "elastic_compliance_matrix",
+    "hardening_descriptor",
+    "hill48_coefficients",
+    "hill48_equivalent_stress",
+    "hill48_strengths",
+    "is_isotropic_material",
+    "is_orthotropic_material",
+    "library",
+    "load_specs",
+    "material_symmetry",
+    "material_validation_errors",
+    "sample_curve",
+    "save_specs",
+    "shell_characteristic_modulus",
+    "shell_material_matrices",
+    "spec_from_material",
+    "steel",
+    "thickness_classes",
+    "user_library_path",
+    "validate_material",
+    "write_curve_svg",
+]

anymaterial/__main__.py

@@ -0,0 +1,351 @@
+"""Command line interface.
+
+``python -m anymaterial <command>``, or ``anymaterial <command>`` once
+installed.  Every command takes ``--json`` for machine-readable output, so the
+tool is usable from a script without parsing formatted text.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Sequence
+
+import numpy as np
+
+from .contract import elastic_compliance_matrix, material_symmetry
+from .library import (
+    STATUSES,
+    LibraryEntry,
+    add_to_user_library,
+    available_grades,
+    dnv_c208_steel_curve,
+    dnv_c208_steel_properties,
+    library,
+    thickness_classes,
+    user_library_path,
+)
+from .plot import sample_curve, write_curve_svg
+from .reductions import beam_material_properties, shell_material_matrices
+from .spec import MaterialSpec, load_specs
+from .validation import material_validation_errors
+
+__all__ = ["main"]
+
+
+def _print_json(payload: Any) -> None:
+    print(json.dumps(payload, indent=2, sort_keys=True, default=float))
+
+
+def _command_grades(args: argparse.Namespace) -> int:
+    payload = {grade: list(thickness_classes(grade)) for grade in available_grades()}
+    if args.json:
+        _print_json(payload)
+        return 0
+    print("DNV-RP-C208 low-fractile steel grades (thickness in mm):")
+    for grade, classes in payload.items():
+        print(f"  {grade}: {', '.join(classes)}")
+    return 0
+
+
+def _command_properties(args: argparse.Namespace) -> int:
+    properties = dnv_c208_steel_properties(
+        args.grade, args.thickness, thickness_class=args.thickness_class
+    )
+    if args.json:
+        _print_json(properties)
+        return 0
+    print(f"{properties['grade']}  thickness {properties['thickness_mm']:g} mm  "
+          f"class {properties['thickness_class']}")
+    print(f"  source          {properties['source']}")
+    print(f"  E               {float(properties['E_pa']) / 1.0e9:.1f} GPa")
+    for key in ("sigma_prop", "sigma_yield", "sigma_yield_2", "K"):
+        print(f"  {key:<15} {float(properties[key]) / 1.0e6:.1f} MPa")
+    for key in ("eps_p_y1", "eps_p_y2", "n"):
+        print(f"  {key:<15} {float(properties[key]):g}")
+    return 0
+
+
+def _command_curve(args: argparse.Namespace) -> int:
+    curve = dnv_c208_steel_curve(args.grade, args.thickness)
+    strains = np.linspace(0.0, float(args.max_strain), int(args.points))
+    stresses = curve.flow_stress(strains)
+    moduli = curve.hardening_modulus(strains)
+    if args.json:
+        _print_json(
+            {
+                "grade": args.grade.upper(),
+                "thickness_m": float(args.thickness),
+                "parameters": curve.as_dict(),
+                "plastic_strain": [float(value) for value in strains],
+                "flow_stress_pa": [float(value) for value in stresses],
+                "hardening_modulus_pa": [float(value) for value in moduli],
+            }
+        )
+        return 0
+    print(f"{'eps_p':>10} {'sigma [MPa]':>14} {'H [MPa]':>14}")
+    for strain, stress, modulus in zip(strains, stresses, moduli):
+        print(f"{strain:>10.5f} {stress / 1.0e6:>14.2f} {modulus / 1.0e6:>14.2f}")
+    return 0
+
+
+def _describe(spec: MaterialSpec) -> Dict[str, Any]:
+    """Summarize one specification, including its derived reductions."""
+
+    material = spec.build()
+    compliance = elastic_compliance_matrix(material)
+    plane_stress, transverse_shear, drilling = shell_material_matrices(material)
+    beam = beam_material_properties(material)
+    return {
+        "name": spec.name,
+        "symmetry": material_symmetry(material),
+        "density": float(spec.density),
+        "yield_stress": float(spec.yield_stress),
+        "nonlinear": spec.is_nonlinear,
+        "hardening": dict(spec.hardening) if spec.hardening else None,
+        "constants": dict(spec.constants),
+        "compliance_diagonal": [float(value) for value in np.diag(compliance)],
+        "shell_plane_stress": [[float(value) for value in row] for row in plane_stress],
+        "shell_transverse_shear": [float(value) for value in np.diag(transverse_shear)],
+        "shell_drilling_shear": float(drilling),
+        "beam": {
+            "axial_modulus": beam.axial_modulus,
+            "shear_modulus_xy": beam.shear_modulus_xy,
+            "shear_modulus_xz": beam.shear_modulus_xz,
+        },
+    }
+
+
+def _command_library(args: argparse.Namespace) -> int:
+    entries = library().find(
+        category=args.category, status=args.status, text=args.search,
+        nonlinear=True if args.nonlinear else None,
+    )
+    if args.json:
+        _print_json({
+            "user_library": str(user_library_path()),
+            "materials": [entry.to_dict() for entry in entries],
+        })
+        return 0
+    if not entries:
+        print("no materials match")
+        return 0
+    # Sized to the content: a fixed width truncated the longer alloy names into
+    # ambiguity, which is the one thing a material listing must not do.
+    name_width = max(len("material"), *(len(entry.name) for entry in entries))
+    category_width = max(len("category"), *(len(entry.category) for entry in entries))
+    print(
+        f"{'material':<{name_width}}  {'category':<{category_width}}  "
+        f"{'status':<10}  {'yield':>9}  hardening"
+    )
+    for entry in entries:
+        yield_mpa = f"{entry.spec.yield_stress / 1.0e6:.0f} MPa" if entry.spec.yield_stress else "-"
+        hardening = entry.spec.hardening["kind"] if entry.spec.hardening else "elastic"
+        print(
+            f"{entry.name:<{name_width}}  {entry.category:<{category_width}}  "
+            f"{entry.status:<10}  {yield_mpa:>9}  {hardening}"
+        )
+    print()
+    print(f"user library: {user_library_path()}")
+    # Said every time the list is printed, because the whole risk this library
+    # carries is a looked-up number being used as a design value.  Only shown for
+    # the statuses actually listed, so the warning stays worth reading.
+    shown = {entry.status for entry in entries}
+    if "measured" in shown:
+        print("status 'measured' is the MEAN of a test campaign, NOT a characteristic value:")
+        print("the mean yield exceeds the nominal, so using it as a design strength is")
+        print("unconservative. Use it to validate a model against the tests it came from.")
+    if "indicative" in shown:
+        print("status 'indicative' means a typical published figure, not a design value:")
+        print("check it against the governing standard or the mill certificate.")
+    if shown <= {"tabulated"}:
+        print("all listed materials are 'tabulated': reproduced from a standard's own table.")
+    return 0
+
+
+def _command_plot(args: argparse.Namespace) -> int:
+    catalogue = library()
+    series = []
+    for name in args.materials:
+        entry = catalogue.get(name)
+        curve = entry.spec.hardening_curve()
+        if curve is None:
+            raise ValueError(
+                f"{name!r} is elastic and has no flow curve to plot; "
+                "list the nonlinear materials with `anymaterial library --nonlinear`"
+            )
+        series.append(sample_curve(curve, name, max_strain=args.max_strain, samples=args.points))
+
+    path = write_curve_svg(
+        args.output, series, overwrite=args.overwrite, title=args.title, stress_unit="MPa"
+    )
+    if args.json:
+        _print_json({"output": str(path), "materials": list(args.materials)})
+    else:
+        print(f"wrote {path} ({len(series)} curve(s))")
+    return 0
+
+
+def _command_add(args: argparse.Namespace) -> int:
+    hardening = None
+    if args.grade:
+        hardening = {"kind": "dnv_c208", "grade": args.grade, "thickness": args.thickness}
+    elif args.hardening_modulus is not None:
+        hardening = {
+            "kind": "linear",
+            "sigma_yield": args.yield_stress * 1.0e6,
+            "hardening_modulus": args.hardening_modulus * 1.0e6,
+        }
+
+    entry = LibraryEntry(
+        spec=MaterialSpec(
+            name=args.name,
+            symmetry="isotropic",
+            constants={
+                "elastic_modulus": args.elastic_modulus * 1.0e9,
+                "poisson_ratio": args.poisson_ratio,
+            },
+            density=args.density,
+            yield_stress=args.yield_stress * 1.0e6,
+            hardening=hardening,
+        ),
+        category=args.category,
+        status="user",
+        standard=args.standard,
+        source=args.source,
+        notes=args.notes,
+    )
+    path = add_to_user_library(entry, replace_existing=args.replace)
+    if args.json:
+        _print_json({"added": entry.name, "library": str(path)})
+    else:
+        print(f"added {entry.name!r} to {path}")
+    return 0
+
+
+def _command_show(args: argparse.Namespace) -> int:
+    summaries = [_describe(spec) for spec in load_specs(args.input)]
+    if args.json:
+        _print_json({"materials": summaries})
+        return 0
+    for summary in summaries:
+        print(f"{summary['name']}  ({summary['symmetry']})")
+        print(f"  density         {summary['density']:g} kg/m3")
+        print(f"  yield stress    {summary['yield_stress'] / 1.0e6:g} MPa")
+        print(f"  nonlinear       {summary['nonlinear']}")
+        if summary["hardening"]:
+            print(f"  hardening       {summary['hardening']}")
+        for key, value in sorted(summary["constants"].items()):
+            print(f"  {key:<15} {value:g}")
+        print(f"  beam E          {summary['beam']['axial_modulus'] / 1.0e9:.2f} GPa")
+        print(f"  drilling G      {summary['shell_drilling_shear'] / 1.0e9:.2f} GPa")
+    return 0
+
+
+def _command_validate(args: argparse.Namespace) -> int:
+    results: List[Dict[str, Any]] = []
+    exit_code = 0
+    for spec in load_specs(args.input):
+        try:
+            material = spec.build()
+        except ValueError as error:
+            results.append({"name": spec.name, "valid": False, "errors": [str(error)]})
+            exit_code = 1
+            continue
+        errors = list(material_validation_errors(material))
+        results.append({"name": spec.name, "valid": not errors, "errors": errors})
+        if errors:
+            exit_code = 1
+
+    if args.json:
+        _print_json({"materials": results})
+        return exit_code
+    for result in results:
+        status = "ok" if result["valid"] else "INVALID"
+        print(f"{result['name']}: {status}")
+        for message in result["errors"]:
+            print(f"  - {message}")
+    return exit_code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="anymaterial", description=__doc__.splitlines()[0])
+    parser.add_argument("--json", action="store_true", help="print machine-readable JSON")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("grades", help="list tabulated steel grades and thickness classes")
+
+    catalogue = sub.add_parser("library", help="list the materials in the library")
+    catalogue.add_argument("--category", help="filter by category, e.g. aluminium")
+    # Derived from the library's own list, so the two cannot drift apart.
+    catalogue.add_argument("--status", choices=STATUSES)
+    catalogue.add_argument("--search", help="filter by name or category substring")
+    catalogue.add_argument("--nonlinear", action="store_true", help="only materials with a flow curve")
+
+    plot = sub.add_parser("plot", help="plot flow curves to an SVG file")
+    plot.add_argument("materials", nargs="+", help="library material names")
+    plot.add_argument("--output", "-o", default="flow_curves.svg")
+    plot.add_argument("--title", default="Flow curves")
+    plot.add_argument("--max-strain", type=float, default=0.10)
+    plot.add_argument("--points", type=int, default=201)
+    plot.add_argument("--overwrite", action="store_true")
+
+    add = sub.add_parser("add", help="add an isotropic material to the user library")
+    add.add_argument("name")
+    add.add_argument("--elastic-modulus", type=float, required=True, help="E in GPa")
+    add.add_argument("--poisson-ratio", type=float, default=0.3)
+    add.add_argument("--density", type=float, default=7850.0, help="kg/m3")
+    add.add_argument("--yield-stress", type=float, default=0.0, help="MPa")
+    add.add_argument("--hardening-modulus", type=float, help="bilinear plastic modulus in MPa")
+    add.add_argument("--grade", help="attach a DNV-RP-C208 curve for this grade instead")
+    add.add_argument("--thickness", type=float, default=0.010, help="metres, with --grade")
+    add.add_argument("--category", default="other")
+    add.add_argument("--standard", help="the standard the numbers come from")
+    add.add_argument("--source", help="where the numbers came from")
+    add.add_argument("--notes")
+    add.add_argument("--replace", action="store_true", help="overwrite a material of the same name")
+
+    properties = sub.add_parser("properties", help="show one RP-C208 table row in SI units")
+    properties.add_argument("grade")
+    properties.add_argument("thickness", type=float, help="plate thickness in metres")
+    properties.add_argument(
+        "--thickness-class",
+        default="auto",
+        help="select a table row explicitly, e.g. '40 < t <= 63'",
+    )
+
+    curve = sub.add_parser("curve", help="sample a flow curve")
+    curve.add_argument("grade")
+    curve.add_argument("thickness", type=float, help="plate thickness in metres")
+    curve.add_argument("--points", type=int, default=11)
+    curve.add_argument("--max-strain", type=float, default=0.1)
+
+    show = sub.add_parser("show", help="summarize materials in a JSON file")
+    show.add_argument("input")
+
+    validate = sub.add_parser("validate", help="validate materials in a JSON file")
+    validate.add_argument("input")
+
+    args = parser.parse_args(argv)
+    handlers = {
+        "grades": _command_grades,
+        "library": _command_library,
+        "plot": _command_plot,
+        "add": _command_add,
+        "properties": _command_properties,
+        "curve": _command_curve,
+        "show": _command_show,
+        "validate": _command_validate,
+    }
+    try:
+        return handlers[args.command](args)
+    except (FileExistsError, FileNotFoundError, KeyError, NotImplementedError, ValueError) as error:
+        # A bad grade, an out-of-range thickness or a malformed file is a usage
+        # error, not a crash: report it on stderr and exit non-zero.
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover - process entry point
+    raise SystemExit(main())

anymaterial/contract.py

@@ -0,0 +1,127 @@
+"""The structural material contract.
+
+A consumer needs four things from a material: a name, a density, a declared
+elastic symmetry, and a 6x6 engineering compliance.  Everything else -- shell
+plane-stress matrices, beam axial and shear constants, yield surfaces -- is
+derived from those, in :mod:`anymaterial.reductions` and elsewhere.
+
+The contract is a :class:`typing.Protocol` rather than a base class on purpose.
+A solver should accept a material without importing the class that defines it,
+which is what allows this package and its consumers to be released
+independently.  Validation is therefore written against attributes, not types.
+
+Voigt order is engineering ``[11, 22, 33, 23, 13, 12]``:
+
+``[eps11, eps22, eps33, gamma23, gamma13, gamma12] = S @
+  [sig11, sig22, sig33, tau23, tau13, tau12]``
+
+Shear strains are engineering angles, twice the tensor components.  Getting
+this wrong scales every shear term by two and is not detectable from the
+diagonal, so the order is stated once here and matched everywhere.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, Tuple, runtime_checkable
+
+import numpy as np
+
+__all__ = [
+    "ENGINEERING_VOIGT_ORDER",
+    "SUPPORTED_ELASTIC_SYMMETRIES",
+    "StructuralMaterial",
+    "elastic_compliance_matrix",
+    "is_isotropic_material",
+    "is_orthotropic_material",
+    "material_symmetry",
+]
+
+
+ENGINEERING_VOIGT_ORDER: Tuple[str, ...] = ("11", "22", "33", "23", "13", "12")
+
+SUPPORTED_ELASTIC_SYMMETRIES = frozenset({"isotropic", "orthotropic"})
+
+
+@runtime_checkable
+class StructuralMaterial(Protocol):
+    """Minimal contract for a structural material."""
+
+    name: str
+    density: float
+    elastic_symmetry: str
+
+    def elastic_compliance_matrix(self) -> np.ndarray:
+        """Return the 6x6 engineering compliance in Voigt order."""
+
+
+def material_symmetry(material: Any) -> str:
+    """Return the normalized declared elastic symmetry.
+
+    Duck-typed isotropic objects that predate the declaration stay recognizable
+    when they expose the historical ``elastic_modulus`` and ``poisson_ratio``
+    fields.  That fallback exists for material records arriving from older
+    callers and deserializers, not as an alternative to declaring the symmetry.
+    """
+
+    symmetry = getattr(material, "elastic_symmetry", None)
+    if symmetry is None and hasattr(material, "elastic_modulus") and hasattr(material, "poisson_ratio"):
+        return "isotropic"
+    if not isinstance(symmetry, str) or not symmetry.strip():
+        raise ValueError(
+            "Structural material must declare elastic_symmetry as 'isotropic' or 'orthotropic'"
+        )
+    return symmetry.strip().lower()
+
+
+def is_isotropic_material(material: Any) -> bool:
+    """Return whether a material declares isotropic elasticity."""
+
+    try:
+        return material_symmetry(material) == "isotropic"
+    except ValueError:
+        return False
+
+
+def is_orthotropic_material(material: Any) -> bool:
+    """Return whether a material declares orthotropic elasticity."""
+
+    try:
+        return material_symmetry(material) == "orthotropic"
+    except ValueError:
+        return False
+
+
+def elastic_compliance_matrix(material: Any) -> np.ndarray:
+    """Return a material's compliance with a stable numpy representation.
+
+    A material that provides ``elastic_compliance_matrix()`` is asked for it.
+    A legacy isotropic record that does not is assembled from ``E`` and ``nu``,
+    so the two reach every reduction by the same path and there is one place
+    for the algebra to be wrong.
+    """
+
+    provider = getattr(material, "elastic_compliance_matrix", None)
+    if callable(provider):
+        matrix = np.asarray(provider(), dtype=float)
+    elif is_isotropic_material(material):
+        E = float(material.elastic_modulus)
+        nu = float(material.poisson_ratio)
+        G = E / (2.0 * (1.0 + nu))
+        matrix = np.array(
+            [
+                [1.0 / E, -nu / E, -nu / E, 0.0, 0.0, 0.0],
+                [-nu / E, 1.0 / E, -nu / E, 0.0, 0.0, 0.0],
+                [-nu / E, -nu / E, 1.0 / E, 0.0, 0.0, 0.0],
+                [0.0, 0.0, 0.0, 1.0 / G, 0.0, 0.0],
+                [0.0, 0.0, 0.0, 0.0, 1.0 / G, 0.0],
+                [0.0, 0.0, 0.0, 0.0, 0.0, 1.0 / G],
+            ],
+            dtype=float,
+        )
+    else:
+        raise ValueError("Structural material must provide elastic_compliance_matrix()")
+    if matrix.shape != (6, 6):
+        raise ValueError(
+            f"Material elastic compliance must have shape (6, 6), received {matrix.shape}"
+        )
+    return matrix