facehard 1.0.0__py3-none-any.whl

facehard/__init__.py

@@ -0,0 +1,51 @@
+"""FACEHARD — native Python port of Nathan Okun's face-hardened armour
+penetration model (FACEHARD 8.0).
+
+Public API:
+    calc(...)         -> Limits          ballistic limits only
+    results(...)      -> Results         limits + post-impact outcome/metrics
+    render_results(...) -> str           original BASIC results narrative
+    penetration(...)  -> float           plate thickness defeated at a velocity
+    armor_info, proj_data                parameter tables
+    names                                menu names (ARMORS / NATIONS / PROJECTILES)
+    Nation, Armor, BackingMetal, *Projectile  named menu numbers (IntEnums);
+                                         projectiles(nation) -> that nation's enum
+"""
+
+from . import names
+from .enums import (
+    Armor,
+    AustroHungarianProjectile,
+    BackingMetal,
+    BritishProjectile,
+    FrenchProjectile,
+    GermanProjectile,
+    ItalianProjectile,
+    JapaneseProjectile,
+    Nation,
+    RussianProjectile,
+    USProjectile,
+    projectiles,
+)
+from .model import (
+    Limits,
+    Results,
+    armor_info,
+    calc,
+    penetration,
+    proj_data,
+    render_results,
+    results,
+)
+
+__version__ = "1.0.0"
+#: Version of Nathan Okun's original QuickBASIC FACEHARD this port reproduces.
+MODEL_VERSION = "8.0"
+__all__ = [
+    "calc", "results", "render_results", "penetration", "Limits", "Results",
+    "armor_info", "proj_data", "names", "__version__", "MODEL_VERSION",
+    "Nation", "Armor", "BackingMetal", "projectiles",
+    "USProjectile", "BritishProjectile", "GermanProjectile", "FrenchProjectile",
+    "ItalianProjectile", "JapaneseProjectile", "AustroHungarianProjectile",
+    "RussianProjectile",
+]

facehard/cli.py

@@ -0,0 +1,339 @@
+"""FACEHARD command-line interface.
+
+    facehard                     interactive wizard (menus)
+    facehard run   [options]     compute one impact; choose --output form
+    facehard pen   [options]     penetration thickness at a striking velocity
+    facehard list  armors|nations|projectiles [--nation N]
+
+Output forms for `run` (--output): narrative | limits | plug | metrics | json | all
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import names
+from .model import Limits, Results, calc, penetration, proj_data, results
+
+# --------------------------------------------------------------------------- #
+# rendering                                                                   #
+# --------------------------------------------------------------------------- #
+def _fmt(v, unit="", nd=0):
+    if v is None:
+        return "n/a"
+    if isinstance(v, float):
+        return f"{v:.{nd}f}{unit}"
+    return f"{v}{unit}"
+
+
+def _header(s: dict) -> str:
+    a = names.ARMORS.get(s["armor"], "?")
+    nat = names.NATIONS.get(s["nation"], "?")
+    pj = names.PROJECTILES.get(s["nation"], {}).get(s["proj"], "?")
+    # `pen` computes the plate thickness, so it has no TA to show; other commands do.
+    ta = s.get("TA")
+    plate = f"{ta:g} in  {a}" if ta is not None else a
+    lines = [
+        f"Plate     : {plate}",
+        f"Projectile: {s['D']:g} in / {s['WT']:g} lb ({nat}, #{s['proj']}: {pj})",
+        f"Impact    : {s['VS']:g} ft/s at {s['OB']:g} deg obliquity",
+    ]
+    if s.get("wood") or s.get("cement") or s.get("metal"):
+        lines.append(f"Backing   : wood {s['wood']:g} / cement {s['cement']:g} / "
+                     f"metal {s['metal']:g} in (type {s['metal_type']}, "
+                     f"{s['metal_plates']} plate)")
+    if s.get("remove", "none") != "none":
+        lines.append(f"Nose       : {s['remove']} removed")
+    return "\n".join(lines)
+
+
+def render_limits(lim: Limits) -> str:
+    def row(tag, label, v):
+        return f"  {tag}  {label:<44} {_fmt(v,' ft/s')}"
+    eff = lim.vitru if lim.vitru is not None else "usually effective (see narrative)"
+    return "\n".join([
+        "BALLISTIC LIMITS (velocity to just defeat the plate):",
+        row("N1", "Navy BL, no shatter, all damage, given cap", lim.vltru),
+        row("N4", "Navy BL, unshattered/undeformed (best case)", lim.vlnd),
+        row("N2", "Navy BL with shatter + all damage", lim.vlshat),
+        row("N3", "Navy BL with shatter, no other damage", lim.vlshatmax),
+        row("H1", "Holing BL, no shatter, given cap", lim.vhtru),
+        row("H4", "Holing BL, unshattered/undeformed", lim.vhnd),
+        row("H2", "Holing BL with shatter", lim.vhshat),
+        row("H3", "Holing BL with shatter, no other damage", lim.vhshatmax),
+        f"  --  {'shatter on impact?':<44} {'yes' if lim.shat else 'no'}",
+    ])
+
+
+def render_plug(res: Results) -> str:
+    return "\n".join([
+        "EJECTED ARMOUR PLUG:",
+        f"  normal plug weight : {_fmt(res.norm_plug_wt,' lb',1)}",
+        f"  delta plug weight  : {_fmt(res.delta_plug_wt,' lb',1)}",
+        f"  total plug weight  : {_fmt(res.total_plug_wt,' lb',1)}",
+        f"  normal plug velocity: {_fmt(res.norm_plug_vel,' ft/s')}",
+    ])
+
+
+def render_metrics(res: Results) -> str:
+    eff = (res.effective_bl if isinstance(res.effective_bl, (int, float))
+           else res.effective_bl)
+    return "\n".join([
+        "METRICS:",
+        f"  outcome            : {res.outcome}",
+        f"  exit angle (Ex)    : {_fmt(res.ex,' deg',2)}",
+        f"  deflection (OB-Ex) : {_fmt(res.obdf,' deg',2)}",
+        f"  remaining velocity : {_fmt(res.remaining_vel,' ft/s')}",
+        f"  effective BL       : {eff if isinstance(eff,str) else _fmt(eff,' ft/s')}",
+        render_plug(res),
+    ])
+
+
+def render_narrative(res: Results, s: dict) -> str:
+    lim = res.limits
+    out = []
+    gun = f"the {s['D']:g}-in shell"
+    if res.pen_flag == 2:
+        out.append(f"COMPLETE PENETRATION. At {s['VS']:g} ft/s and {s['OB']:g} deg, "
+                   f"{gun} passes entirely through the {s['TA']:g}-in plate.")
+        if res.remaining_vel:
+            out.append(f"It exits at ~{res.remaining_vel:.0f} ft/s, deflected to an "
+                       f"exit angle of {res.ex:.1f} deg (turned {res.obdf:.1f} deg "
+                       f"from its line of flight).")
+        if res.total_plug_wt:
+            out.append(f"A ~{res.total_plug_wt:.0f} lb armour plug is punched out of "
+                       f"the back at ~{res.norm_plug_vel:.0f} ft/s.")
+    elif res.pen_flag == 1:
+        out.append(f"HOLING ONLY. {gun.capitalize()} makes a hole through the plate "
+                   f"but does not achieve a clean complete penetration; effect behind "
+                   f"the plate is reduced.")
+        if res.total_plug_wt:
+            out.append(f"A ~{res.total_plug_wt:.0f} lb plug/spall is thrown from the back.")
+    else:
+        out.append(f"NO PENETRATION. At {s['VS']:g} ft/s {gun} fails to hole the "
+                   f"{s['TA']:g}-in plate; only shock and possible back-spall behind it.")
+    if lim.shat:
+        if res.body_damage < 2:
+            out.append("The projectile suffers nose-only shatter, but its lower body "
+                       "remains substantially intact.")
+        else:
+            out.append("The projectile shatters on impact (nose/body break-up).")
+    eff = res.effective_bl
+    eff_txt = eff if isinstance(eff, str) else f"~{eff:.0f} ft/s"
+    out.append(f"Navy (complete-pen) limit is ~{lim.vltru:.0f} ft/s; "
+               f"'effective' limit (pen + able to burst) is {eff_txt}.")
+    return "PREDICTION:\n  " + "\n  ".join(out)
+
+
+def render(res: Results, s: dict, form: str) -> str:
+    lim = res.limits
+    if form == "limits":
+        return render_limits(lim)
+    if form == "plug":
+        return render_plug(res)
+    if form == "metrics":
+        return render_metrics(res)
+    if form == "json":
+        import dataclasses
+        d = dataclasses.asdict(res)
+        d["scenario"] = s
+        return json.dumps(d, indent=2, default=str)
+    if form == "all":
+        return "\n\n".join([render_narrative(res, s), render_limits(lim),
+                            render_metrics(res)])
+    return render_narrative(res, s)     # default
+
+
+# --------------------------------------------------------------------------- #
+# scenario extraction                                                         #
+# --------------------------------------------------------------------------- #
+SCEN_KEYS = ("armor", "nation", "proj", "TA", "D", "WT", "WB", "OB", "VS",
+             "wood", "cement", "metal", "metal_type", "metal_plates",
+             "remove", "windscreen_wt", "caphead_wt")
+
+
+def _scen_from_args(a) -> dict:
+    return dict(armor=a.armor, nation=a.nation, proj=a.proj, TA=a.thickness,
+                D=a.diameter, WT=a.weight, WB=a.body_weight, OB=a.obliquity,
+                VS=a.velocity, wood=a.wood, cement=a.cement, metal=a.metal,
+                metal_type=a.metal_type, metal_plates=a.metal_plates,
+                remove=a.remove, windscreen_wt=a.windscreen_wt,
+                caphead_wt=a.caphead_wt)
+
+
+def _add_scenario_args(p, need_velocity=True, need_thickness=True):
+    p.add_argument("--armor", type=int, required=True, metavar="1-25")
+    p.add_argument("--nation", type=int, required=True, metavar="1-8")
+    p.add_argument("--proj", type=int, required=True, metavar="N")
+    # `pen` inverts the model to find thickness, so it does not take -t.
+    p.add_argument("-t", "--thickness", type=float, required=need_thickness,
+                   help="plate TA, in")
+    p.add_argument("-d", "--diameter", type=float, required=True, help="calibre D, in")
+    p.add_argument("-w", "--weight", type=float, required=True, help="total weight WT, lb")
+    p.add_argument("-b", "--body-weight", type=float, required=True, dest="body_weight",
+                   help="body weight WB, lb (< WT)")
+    p.add_argument("-o", "--obliquity", type=float, default=0.0, help="obliquity OB, deg")
+    if need_velocity:
+        p.add_argument("-v", "--velocity", type=float, required=True,
+                       help="striking velocity VS, ft/s")
+    # backing
+    p.add_argument("--wood", type=float, default=0.0)
+    p.add_argument("--cement", type=float, default=0.0)
+    p.add_argument("--metal", type=float, default=0.0)
+    p.add_argument("--metal-type", type=int, default=5, dest="metal_type")
+    p.add_argument("--metal-plates", type=int, default=1, dest="metal_plates")
+    # nose-covering loss
+    p.add_argument("--remove", choices=["none", "cap", "windscreen", "caphead"],
+                   default="none")
+    p.add_argument("--windscreen-wt", type=float, default=0.0, dest="windscreen_wt")
+    p.add_argument("--caphead-wt", type=float, default=0.0, dest="caphead_wt")
+
+
+# --------------------------------------------------------------------------- #
+# interactive wizard                                                          #
+# --------------------------------------------------------------------------- #
+def _pick(title: str, options: dict[int, str], default: int | None = None) -> int:
+    print(f"\n{title}")
+    for k in sorted(options):
+        print(f"  {k:>3}. {options[k]}")
+    while True:
+        d = f" [{default}]" if default else ""
+        raw = input(f"Select{d}: ").strip()
+        if raw == "" and default is not None:
+            return default
+        if raw.isdigit() and int(raw) in options:
+            return int(raw)
+        print("  invalid selection")
+
+
+def _ask(prompt: str, cast=float, default=None):
+    while True:
+        d = f" [{default}]" if default is not None else ""
+        raw = input(f"{prompt}{d}: ").strip()
+        if raw == "" and default is not None:
+            return default
+        try:
+            return cast(raw)
+        except ValueError:
+            print("  invalid number")
+
+
+def wizard() -> int:
+    print("FACEHARD interactive scenario builder\n" + "=" * 38)
+    armor = _pick("ARMOUR TYPE", names.ARMORS, default=14)
+    nation = _pick("PROJECTILE NATION", names.NATIONS, default=1)
+    proj = _pick("PROJECTILE TYPE", names.PROJECTILES[nation])
+    TA = _ask("Plate thickness (in)", float, 12.0)
+    D = _ask("Projectile calibre (in)", float, 16.0)
+    WT = _ask("Total weight (lb)", float, 2700.0)
+    WB = _ask("Body weight (lb, < total)", float, round(WT * 0.82, 1))
+    VS = _ask("Striking velocity (ft/s)", float, 2000.0)
+    OB = _ask("Impact obliquity (deg)", float, 0.0)
+    s = dict(armor=armor, nation=nation, proj=proj, TA=TA, D=D, WT=WT, WB=WB,
+             OB=OB, VS=VS, wood=0.0, cement=0.0, metal=0.0, metal_type=5,
+             metal_plates=1, remove="none", windscreen_wt=0.0, caphead_wt=0.0)
+    if input("\nAdd backing behind the plate? (y/N) ").strip().lower() == "y":
+        s["wood"] = _ask("  wood thickness (in)", float, 0.0)
+        s["cement"] = _ask("  cement thickness (in)", float, 0.0)
+        s["metal"] = _ask("  metal thickness (in)", float, 0.0)
+        if s["metal"] > 0:
+            s["metal_type"] = _ask("  metal type 1-5", int, 5)
+            s["metal_plates"] = _ask("  number of plates", int, 1)
+    form = _pick("OUTPUT", {1: "narrative", 2: "limits", 3: "metrics",
+                            4: "everything", 5: "json"}, default=1)
+    form = {1: "narrative", 2: "limits", 3: "metrics", 4: "all", 5: "json"}[form]
+    res = results(**s)
+    print("\n" + _header(s) + "\n\n" + render(res, s, form))
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# main                                                                        #
+# --------------------------------------------------------------------------- #
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="facehard",
+        description="Face-hardened naval armour penetration (Nathan Okun's "
+                    "FACEHARD 8.0, native Python port).")
+    p.add_argument("--version", action="store_true")
+    sub = p.add_subparsers(dest="cmd")
+
+    pr = sub.add_parser("run", help="compute one impact")
+    _add_scenario_args(pr)
+    pr.add_argument("-O", "--output",
+                    choices=["narrative", "limits", "plug", "metrics", "json", "all"],
+                    default="narrative")
+
+    pp = sub.add_parser("pen", help="penetration thickness at a striking velocity")
+    _add_scenario_args(pp, need_thickness=False)   # pen computes the thickness
+
+    sub.add_parser("emulate", help="run the original FACEHARD interactive flow")
+
+    pl = sub.add_parser("list", help="list menu options")
+    pl.add_argument("what", choices=["armors", "nations", "projectiles"])
+    pl.add_argument("--nation", type=int, default=1)
+
+    args = p.parse_args(argv)
+
+    if args.version:
+        from . import MODEL_VERSION, __version__
+        print(f"facehard {__version__} (FACEHARD model {MODEL_VERSION})")
+        return 0
+
+    if args.cmd is None:
+        try:
+            return wizard()
+        except (KeyboardInterrupt, EOFError):
+            print("\naborted")
+            return 1
+
+    if args.cmd == "list":
+        if args.what == "armors":
+            for k in sorted(names.ARMORS):
+                print(f"{k:>3}. {names.ARMORS[k]}")
+        elif args.what == "nations":
+            for k in sorted(names.NATIONS):
+                print(f"{k}. {names.NATIONS[k]}")
+        else:
+            print(f"Projectiles for {names.NATIONS.get(args.nation, '?')}:")
+            for k in sorted(names.PROJECTILES.get(args.nation, {})):
+                print(f"{k:>3}. {names.PROJECTILES[args.nation][k]}")
+        return 0
+
+    if args.cmd == "emulate":
+        from .emulate import main as emulate_main
+        return emulate_main()
+
+    s = _scen_from_args(args)
+    if s["WB"] >= s["WT"] and s["remove"] == "none":
+        print("warning: body weight >= total weight (shell has no cap/windscreen)",
+              file=sys.stderr)
+
+    if args.cmd == "pen":
+        try:
+            t = penetration(armor=s["armor"], nation=s["nation"], proj=s["proj"],
+                            D=s["D"], WT=s["WT"], WB=s["WB"], V=s["VS"], OB=s["OB"])
+        except ValueError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+        a = names.ARMORS.get(s["armor"], "?")
+        print(_header(s))
+        print(f"\nPENETRATION: {t:.1f} in of [{a}] defeated at {s['VS']:g} ft/s, "
+              f"{s['OB']:g} deg (substantially intact, non-immobilised body basis).")
+        return 0
+
+    # run
+    res = results(**s)
+    if args.output == "json":
+        print(render(res, s, "json"))       # pure JSON, no header
+    else:
+        print(_header(s))
+        print()
+        print(render(res, s, args.output))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())