molbuilder 1.0.0__py3-none-any.whl

molbuilder/reports/cost_report.py

@@ -0,0 +1,206 @@
+"""Cost estimation report generator.
+
+Produces an ASCII cost breakdown report with summary, category
+breakdown table, bar chart, percentage distribution, and notes.
+All output is cp1252-safe.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from molbuilder.reports.text_formatter import (
+    section_header,
+    subsection_header,
+    ascii_table,
+    bullet_list,
+    key_value_block,
+    horizontal_bar,
+    format_currency,
+    format_percent,
+    word_wrap,
+)
+
+if TYPE_CHECKING:
+    from molbuilder.reports import CostEstimateLike
+
+
+# =====================================================================
+#  Helpers
+# =====================================================================
+
+_CATEGORY_LABELS: list[tuple[str, str]] = [
+    ("raw_materials_usd",   "Raw Materials"),
+    ("labor_usd",           "Labor"),
+    ("equipment_usd",       "Equipment"),
+    ("energy_usd",          "Energy"),
+    ("waste_disposal_usd",  "Waste Disposal"),
+    ("overhead_usd",        "Overhead"),
+]
+
+
+def _safe_float(value, default: float = 0.0) -> float:
+    """Coerce *value* to float, returning *default* on failure."""
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+# =====================================================================
+#  Public API
+# =====================================================================
+
+def generate_cost_report(estimate: CostEstimateLike) -> str:
+    """Generate an ASCII cost breakdown report.
+
+    Uses duck typing -- *estimate* should expose:
+
+    * ``.total_usd`` -- float, total estimated cost
+    * ``.per_kg_usd`` -- float, cost per kilogram of product
+    * ``.scale_kg`` -- float, production scale in kg
+    * ``.breakdown`` -- object with attributes:
+        - ``.raw_materials_usd``
+        - ``.labor_usd``
+        - ``.equipment_usd``
+        - ``.energy_usd``
+        - ``.waste_disposal_usd``
+        - ``.overhead_usd``
+    * ``.notes`` -- list[str], assumptions and caveats
+    """
+    if not hasattr(estimate, 'total_usd'):
+        raise TypeError(
+            f"estimate must have a 'total_usd' attribute, "
+            f"got {type(estimate).__name__}"
+        )
+
+    lines: list[str] = []
+
+    # ------------------------------------------------------------------
+    # 1. Header
+    # ------------------------------------------------------------------
+    lines.append(section_header("Cost Estimation Report"))
+    lines.append("")
+
+    # ------------------------------------------------------------------
+    # 2. Summary
+    # ------------------------------------------------------------------
+    lines.append(subsection_header("Summary"))
+
+    total = _safe_float(getattr(estimate, "total_usd", None))
+    per_kg = _safe_float(getattr(estimate, "per_kg_usd", None))
+    scale = _safe_float(getattr(estimate, "scale_kg", None))
+
+    summary_pairs = [
+        ("Production Scale",  f"{scale:.2f} kg"),
+        ("Total Cost",        format_currency(total)),
+        ("Cost per kg",       format_currency(per_kg)),
+    ]
+    lines.append(key_value_block(summary_pairs))
+    lines.append("")
+
+    # ------------------------------------------------------------------
+    # 3. Cost Breakdown -- table and bar chart
+    # ------------------------------------------------------------------
+    lines.append(subsection_header("Cost Breakdown"))
+
+    breakdown = getattr(estimate, "breakdown", None)
+    categories: list[tuple[str, float]] = []
+    for attr, label in _CATEGORY_LABELS:
+        val = _safe_float(getattr(breakdown, attr, None) if breakdown else None)
+        categories.append((label, val))
+
+    # Table
+    tbl_headers = ["Category", "Amount (USD)", "% of Total"]
+    tbl_rows: list[list[str]] = []
+    for label, amount in categories:
+        pct = (amount / total * 100.0) if total > 0 else 0.0
+        tbl_rows.append([
+            label,
+            format_currency(amount),
+            format_percent(pct),
+        ])
+    # Total row
+    tbl_rows.append([
+        "TOTAL",
+        format_currency(total),
+        format_percent(100.0) if total > 0 else format_percent(0.0),
+    ])
+
+    lines.append(ascii_table(
+        tbl_headers, tbl_rows,
+        alignments=["l", "r", "r"],
+        min_widths=[16, 14, 10],
+    ))
+    lines.append("")
+
+    # Bar chart
+    lines.append(subsection_header("Cost Distribution (Bar Chart)"))
+    max_amount = max((amt for _, amt in categories), default=0.0)
+    max_label_len = max((len(label) for label, _ in categories), default=0)
+
+    for label, amount in categories:
+        bar = horizontal_bar(amount, max_amount, width=35, char="#")
+        amount_str = format_currency(amount)
+        lines.append(
+            f"  {label:<{max_label_len}}  |{bar}| {amount_str}"
+        )
+    lines.append("")
+
+    # ------------------------------------------------------------------
+    # 4. Percentage Distribution
+    # ------------------------------------------------------------------
+    lines.append(subsection_header("Percentage Distribution"))
+
+    pct_headers = ["Category", "Percentage", "Visual"]
+    pct_rows: list[list[str]] = []
+    for label, amount in categories:
+        pct = (amount / total * 100.0) if total > 0 else 0.0
+        bar = horizontal_bar(pct, 100.0, width=20, char="=")
+        pct_rows.append([label, format_percent(pct), bar])
+
+    lines.append(ascii_table(
+        pct_headers, pct_rows,
+        alignments=["l", "r", "l"],
+        min_widths=[16, 10, 20],
+    ))
+    lines.append("")
+
+    # ------------------------------------------------------------------
+    # 5. Notes and Assumptions
+    # ------------------------------------------------------------------
+    lines.append(subsection_header("Notes and Assumptions"))
+
+    notes = getattr(estimate, "notes", None)
+    if notes and hasattr(notes, "__iter__") and not isinstance(notes, str):
+        note_list = [str(n) for n in notes if n]
+    elif notes:
+        note_list = [str(notes)]
+    else:
+        note_list = []
+
+    if note_list:
+        lines.append(bullet_list(note_list))
+    else:
+        lines.append("  No additional notes.")
+    lines.append("")
+
+    # Standard disclaimer
+    lines.append(subsection_header("Disclaimer"))
+    disclaimer = (
+        "This cost estimate is for planning purposes only.  Actual costs "
+        "may vary based on supplier pricing, scale-up effects, local "
+        "labor rates, and regulatory requirements.  All figures are "
+        "approximate and should be validated before procurement."
+    )
+    lines.append(word_wrap(disclaimer, width=66, indent=2))
+    lines.append("")
+
+    # Footer
+    lines.append("=" * 70)
+    lines.append("  End of Cost Estimation Report")
+    lines.append("=" * 70)
+
+    return "\n".join(lines)

molbuilder/reports/molecule_report.py

@@ -0,0 +1,279 @@
+"""Molecule report generator.
+
+Produces a comprehensive ASCII report about a molecule's composition,
+bonding, functional groups, and connectivity.  All output is cp1252-safe.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from typing import TYPE_CHECKING
+
+from molbuilder.reports.text_formatter import (
+    section_header,
+    subsection_header,
+    ascii_table,
+    bullet_list,
+    key_value_block,
+    format_percent,
+)
+
+if TYPE_CHECKING:
+    from molbuilder.reports import MoleculeLike
+
+# Attempt to import functional-group detection.  If the reactions module
+# is unavailable the report simply omits that section.
+try:
+    from molbuilder.reactions.functional_group_detect import detect_functional_groups as _detect_fg
+    _HAS_FG_DETECT = True
+except Exception:
+    _HAS_FG_DETECT = False
+
+
+# Standard atomic weights for the most common organic elements (g/mol).
+_ATOMIC_WEIGHTS: dict[str, float] = {
+    "H":   1.008,
+    "He":  4.003,
+    "Li":  6.941,
+    "Be":  9.012,
+    "B":  10.811,
+    "C":  12.011,
+    "N":  14.007,
+    "O":  15.999,
+    "F":  18.998,
+    "Ne": 20.180,
+    "Na": 22.990,
+    "Mg": 24.305,
+    "Al": 26.982,
+    "Si": 28.086,
+    "P":  30.974,
+    "S":  32.065,
+    "Cl": 35.453,
+    "Ar": 39.948,
+    "K":  39.098,
+    "Ca": 40.078,
+    "Ti": 47.867,
+    "Cr": 51.996,
+    "Mn": 54.938,
+    "Fe": 55.845,
+    "Co": 58.933,
+    "Ni": 58.693,
+    "Cu": 63.546,
+    "Zn": 65.380,
+    "Br": 79.904,
+    "I": 126.904,
+    "Pd": 106.42,
+    "Sn": 118.71,
+    "Pt": 195.08,
+}
+
+
+def _hill_formula(counts: dict[str, int]) -> str:
+    """Return molecular formula in Hill system order.
+
+    Hill system: C first, then H, then everything else alphabetically.
+    If no carbon, all elements alphabetically.
+    """
+    parts: list[str] = []
+    remaining = dict(counts)
+
+    if "C" in remaining:
+        n = remaining.pop("C")
+        parts.append("C" if n == 1 else f"C{n}")
+        if "H" in remaining:
+            n = remaining.pop("H")
+            parts.append("H" if n == 1 else f"H{n}")
+
+    for elem in sorted(remaining.keys()):
+        n = remaining[elem]
+        parts.append(elem if n == 1 else f"{elem}{n}")
+
+    return "".join(parts)
+
+
+def _molecular_weight(counts: dict[str, int]) -> float:
+    """Compute molecular weight from element counts."""
+    total = 0.0
+    for elem, n in counts.items():
+        total += _ATOMIC_WEIGHTS.get(elem, 0.0) * n
+    return total
+
+
+def _bond_order_label(order) -> str:
+    """Human-readable bond order label."""
+    try:
+        order_val = float(order)
+    except (TypeError, ValueError):
+        return "unknown"
+    if order_val == 1.0:
+        return "single"
+    if order_val == 1.5:
+        return "aromatic"
+    if order_val == 2.0:
+        return "double"
+    if order_val == 3.0:
+        return "triple"
+    return f"order {order_val}"
+
+
+# =====================================================================
+#  Public API
+# =====================================================================
+
+def generate_molecule_report(mol: MoleculeLike) -> str:
+    """Generate a comprehensive ASCII report about a molecule.
+
+    Uses duck typing -- *mol* should expose:
+
+    * ``.name`` -- molecule name (str)
+    * ``.atoms`` -- list of atom objects with ``.symbol``
+    * ``.bonds`` -- list of bond objects with ``.atom_i``, ``.atom_j``, ``.order``
+    * ``.neighbors(idx)`` -- list of bonded-atom indices
+    * ``.get_bond(i, j)`` -- Bond object or None
+
+    Returns a single multi-line string.
+    """
+    if not hasattr(mol, 'atoms'):
+        raise TypeError(
+            f"mol must have an 'atoms' attribute, "
+            f"got {type(mol).__name__}"
+        )
+
+    lines: list[str] = []
+
+    # ------------------------------------------------------------------
+    # 1. Header
+    # ------------------------------------------------------------------
+    mol_name = getattr(mol, "name", "Unknown") or "Unknown"
+    lines.append(section_header(f"Molecule Report: {mol_name}"))
+    lines.append("")
+
+    atoms = getattr(mol, "atoms", [])
+    bonds = getattr(mol, "bonds", [])
+
+    # ------------------------------------------------------------------
+    # 2. Basic Properties
+    # ------------------------------------------------------------------
+    elem_counts: Counter[str] = Counter()
+    for atom in atoms:
+        elem_counts[atom.symbol] += 1
+
+    formula = _hill_formula(dict(elem_counts))
+    mw = _molecular_weight(dict(elem_counts))
+
+    lines.append(subsection_header("Basic Properties"))
+    props = [
+        ("Molecular Formula", formula),
+        ("Molecular Weight",  f"{mw:.3f} g/mol"),
+        ("Total Atoms",       str(len(atoms))),
+        ("Total Bonds",       str(len(bonds))),
+    ]
+    lines.append(key_value_block(props))
+    lines.append("")
+
+    # ------------------------------------------------------------------
+    # 3. Atom Composition
+    # ------------------------------------------------------------------
+    lines.append(subsection_header("Atom Composition"))
+    comp_headers = ["Element", "Count", "Mass (g/mol)", "Mass %"]
+    comp_rows: list[list[str]] = []
+    for elem in sorted(elem_counts.keys()):
+        count = elem_counts[elem]
+        mass = _ATOMIC_WEIGHTS.get(elem, 0.0) * count
+        pct = (mass / mw * 100.0) if mw > 0 else 0.0
+        comp_rows.append([
+            elem,
+            str(count),
+            f"{mass:.3f}",
+            format_percent(pct),
+        ])
+    lines.append(ascii_table(
+        comp_headers, comp_rows,
+        alignments=["l", "r", "r", "r"],
+        min_widths=[8, 6, 12, 8],
+    ))
+    lines.append("")
+
+    # ------------------------------------------------------------------
+    # 4. Bond Summary
+    # ------------------------------------------------------------------
+    lines.append(subsection_header("Bond Summary"))
+    order_counts: Counter[str] = Counter()
+    for bond in bonds:
+        label = _bond_order_label(bond.order)
+        order_counts[label] += 1
+
+    bond_headers = ["Bond Type", "Count"]
+    bond_rows = [[btype, str(cnt)]
+                 for btype, cnt in sorted(order_counts.items())]
+    lines.append(ascii_table(
+        bond_headers, bond_rows,
+        alignments=["l", "r"],
+        min_widths=[12, 6],
+    ))
+    lines.append("")
+
+    # ------------------------------------------------------------------
+    # 5. Functional Groups
+    # ------------------------------------------------------------------
+    if _HAS_FG_DETECT:
+        lines.append(subsection_header("Functional Groups"))
+        try:
+            groups = _detect_fg(mol)
+            if groups:
+                fg_names = [g.name for g in groups]
+                fg_counts: Counter[str] = Counter(fg_names)
+                fg_items = [
+                    f"{name} (x{cnt})" if cnt > 1 else name
+                    for name, cnt in sorted(fg_counts.items())
+                ]
+                lines.append(bullet_list(fg_items))
+            else:
+                lines.append("  No common functional groups detected.")
+        except Exception:
+            lines.append("  Functional group detection unavailable.")
+        lines.append("")
+
+    # ------------------------------------------------------------------
+    # 6. Connectivity
+    # ------------------------------------------------------------------
+    lines.append(subsection_header("Connectivity"))
+
+    # Degree distribution
+    degree_counts: Counter[int] = Counter()
+    for idx in range(len(atoms)):
+        try:
+            nbrs = mol.neighbors(idx)
+            degree_counts[len(nbrs)] += 1
+        except Exception:
+            pass
+
+    if degree_counts:
+        deg_headers = ["Degree", "Atom Count"]
+        deg_rows = [[str(d), str(c)]
+                    for d, c in sorted(degree_counts.items())]
+        lines.append(ascii_table(
+            deg_headers, deg_rows,
+            alignments=["r", "r"],
+            min_widths=[8, 12],
+        ))
+    lines.append("")
+
+    # Ring detection heuristic (Euler formula: rings = bonds - atoms + 1
+    # for connected graph).  This gives the cyclomatic number.
+    n_atoms = len(atoms)
+    n_bonds = len(bonds)
+    ring_count = n_bonds - n_atoms + 1
+    if ring_count > 0:
+        lines.append(f"  Ring structures detected (cyclomatic number: {ring_count})")
+    else:
+        lines.append("  No ring structures detected (acyclic molecule)")
+    lines.append("")
+
+    # Footer
+    lines.append("=" * 70)
+    lines.append("  End of Molecule Report")
+    lines.append("=" * 70)
+
+    return "\n".join(lines)