Add material database and Ashby maps

docs/ashby/bridge.rst

@@ -0,0 +1,67 @@
+Simcoon Bridge
+==============
+
+The bridge module converts ``Material`` objects into simcoon-compatible
+stiffness and compliance tensors.  This lets you go directly from a material
+database query to a simcoon simulation.
+
+.. autofunction:: simcoon.ashby.bridge.to_stiffness
+.. autofunction:: simcoon.ashby.bridge.to_compliance
+.. autofunction:: simcoon.ashby.bridge.to_solver_props
+
+Unit conversion
+---------------
+
+Material properties in the Ashby module are stored in **GPa** (elastic moduli)
+and **MPa** (strengths), following common engineering-data conventions.
+Simcoon's internal convention is **MPa** for all stresses and moduli.
+
+The ``unit_factor`` parameter (default ``1e3``) handles the GPa → MPa
+conversion automatically.  If your material data is already in MPa, pass
+``unit_factor=1``.
+
+Example
+-------
+
+.. code-block:: python
+
+   from simcoon.ashby import load_builtin, to_stiffness, to_compliance, to_solver_props
+
+   mats = load_builtin()
+   al = [m for m in mats if "6061" in m.name][0]
+
+   # 6x6 stiffness tensor (MPa)
+   L = to_stiffness(al)
+
+   # 6x6 compliance tensor (1/MPa)
+   M = to_compliance(al)
+
+   # Ready-made dict for sim.solver()
+   sp = to_solver_props(al)
+   # {'umat_name': 'ELISO', 'props': array([68900., 0.33]), 'nstatev': 1}
+
+Supported symmetries
+--------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - SymmetryType
+     - simcoon function
+     - Required Material fields
+   * - ``ISOTROPIC``
+     - ``sim.L_iso`` / ``sim.M_iso``
+     - ``E``, ``nu``
+   * - ``CUBIC``
+     - ``sim.L_cubic`` / ``sim.M_cubic``
+     - ``E``, ``nu``, ``G``
+   * - ``TRANSVERSE_ISOTROPIC``
+     - (full tensor pass-through)
+     - ``elastic_tensor`` (6x6)
+   * - ``ORTHOTROPIC``
+     - (full tensor pass-through)
+     - ``elastic_tensor`` (6x6)
+
+For transversely isotropic and orthotropic materials the bridge requires the
+full ``elastic_tensor`` field to be populated (e.g. from Materials Project).

docs/ashby/data.rst

@@ -0,0 +1,63 @@
+Dataset Loaders
+===============
+
+Functions for loading material datasets, either from the bundled JSON file
+or from user-supplied CSV files.
+
+.. autofunction:: simcoon.ashby.data.load_builtin
+
+.. autofunction:: simcoon.ashby.data.load_csv
+
+Built-in dataset
+----------------
+
+The bundled ``materials.json`` contains ~60 curated engineering materials
+drawn from standard references.  The dataset covers five material families:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 10 65
+
+   * - Category
+     - Count
+     - Examples
+   * - Metal
+     - 24
+     - Mild steel, AISI 304/316L, Al 6061-T6/7075-T6, Ti-6Al-4V, Inconel 718, Cu, Brass, W, …
+   * - Ceramic
+     - 10
+     - Alumina, SiC, Si₃N₄, ZrO₂, B₄C, WC, soda-lime glass, fused silica, …
+   * - Polymer
+     - 15
+     - HDPE, LDPE, PP, PVC, PMMA, Nylon 6.6, PET, PTFE, PC, ABS, epoxy, …
+   * - Composite
+     - 5
+     - CFRP (UD), CFRP (woven), GFRP, Aramid/epoxy, plywood
+   * - Foam
+     - 3
+     - PU foam, aluminium foam, cork
+
+Every entry includes at least ``E``, ``nu``, and ``density``.  Many metals
+also provide ``yield_strength``, ``tensile_strength``, and hardening
+parameters.
+
+Loading a CSV file
+------------------
+
+Any CSV file with a header row can be imported.  Columns whose names match
+``Material`` fields are used automatically; others are ignored.
+
+.. code-block:: python
+
+   from simcoon.ashby import load_csv
+
+   # Direct match — CSV headers = Material field names
+   mats = load_csv("my_materials.csv")
+
+   # With column renaming
+   mats = load_csv("lab_data.csv", column_mapping={
+       "Material": "name",
+       "Youngs_GPa": "E",
+       "Poisson": "nu",
+       "Rho_kg_m3": "density",
+   })

docs/ashby/database.rst

@@ -0,0 +1,71 @@
+Database Integration
+====================
+
+The ``database`` module provides functions to fetch material data from
+online databases.  Currently the `Materials Project <https://materialsproject.org>`_
+is supported via the ``mp-api`` package.
+
+.. autofunction:: simcoon.ashby.database.fetch_materials
+
+Requirements
+------------
+
+Database queries require the ``mp-api`` package:
+
+.. code-block:: bash
+
+   pip install 'simcoon[ashby]'
+
+You also need a Materials Project API key.  Sign up at
+https://materialsproject.org and set the key either as an environment
+variable:
+
+.. code-block:: bash
+
+   export MP_API_KEY="your_key_here"
+
+or pass it directly:
+
+.. code-block:: python
+
+   from simcoon.ashby import fetch_materials
+   mats = fetch_materials(elements=["Al"], api_key="your_key_here")
+
+Example
+-------
+
+.. code-block:: python
+
+   from simcoon.ashby import fetch_materials, ashby_plot
+
+   # Fetch aluminium-containing compounds with elastic data
+   al_mats = fetch_materials(elements=["Al", "O"], limit=50)
+   print(f"Fetched {len(al_mats)} materials")
+
+   # Inspect the first entry
+   m = al_mats[0]
+   print(m.name, m.source_id, m.E, m.nu)
+
+   # Plot an Ashby diagram of the fetched data
+   ashby_plot(al_mats, "density", "E", group_by="category")
+
+Combining with the built-in dataset
+------------------------------------
+
+.. code-block:: python
+
+   from simcoon.ashby import load_builtin, fetch_materials, MaterialCollection
+
+   builtin = load_builtin()
+   online  = fetch_materials(elements=["Ti"], limit=30)
+
+   combined = MaterialCollection(list(builtin) + list(online))
+
+Symmetry detection
+------------------
+
+When the Materials Project returns a full elastic tensor, the module
+automatically calls ``simcoon.check_symetries()`` to determine the material
+symmetry (isotropic, cubic, orthotropic, etc.).  This information is stored
+in the ``symmetry`` field and used by the :doc:`bridge` to select the
+correct simcoon tensor constructor.

docs/ashby/index.rst

@@ -0,0 +1,81 @@
+The Ashby Module
+================
+
+The ``simcoon.ashby`` subpackage provides tools for working with material
+property databases and creating Ashby-style material selection charts.  It
+bridges the gap between material data (from curated datasets or online
+databases like Materials Project) and simcoon's constitutive modelling
+functions.
+
+Highlights
+----------
+
+- **Built-in dataset** of ~60 common engineering materials (metals, ceramics,
+  polymers, composites, foams) with elastic, thermal, and strength properties.
+- **Ashby diagram plotting** with automatic grouping by material family,
+  envelope drawing (ellipse, convex hull), and performance-index guide lines.
+- **Materials Project integration** — fetch elastic properties for thousands
+  of crystalline compounds directly from the Materials Project API.
+- **Simcoon bridge** — convert any material to a 6x6 stiffness or compliance
+  tensor ready for use with ``sim.L_iso()``, ``sim.solver()``, etc.
+
+Installation
+------------
+
+The core data model (``Material``, ``load_builtin()``) requires only
+**numpy**, which is already a simcoon dependency.
+
+For plotting and database features, install the optional ``ashby`` extras:
+
+.. code-block:: bash
+
+   pip install 'simcoon[ashby]'
+
+This pulls in ``matplotlib``, ``scipy``, and ``mp-api``.
+
+Quick start
+-----------
+
+.. code-block:: python
+
+   from simcoon.ashby import load_builtin, ashby_plot, to_stiffness
+
+   # 1. Load the curated material dataset
+   mats = load_builtin()                          # ~60 materials, no optional deps
+
+   # 2. Create an Ashby diagram
+   ax = ashby_plot(mats, "density", "E")           # E vs density, log-log
+
+   # 3. Convert a material to a simcoon stiffness tensor
+   steel = mats.filter(category="Metal")[0]
+   L = to_stiffness(steel)                         # 6x6 ndarray in MPa
+
+Package structure
+-----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Module
+     - Description
+   * - :doc:`material`
+     - ``Material`` dataclass, ``SymmetryType`` enum, ``MaterialCollection``
+   * - :doc:`data`
+     - Built-in dataset loader (``load_builtin``) and CSV importer (``load_csv``)
+   * - :doc:`plotting`
+     - ``ashby_plot()`` and legacy visualization helpers
+   * - :doc:`bridge`
+     - Convert materials to simcoon stiffness/compliance tensors
+   * - :doc:`database`
+     - Fetch materials from the Materials Project API
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   material
+   data
+   plotting
+   bridge
+   database