facehard 1.0.0__tar.gz

facehard-1.0.0/LICENSE

@@ -0,0 +1,151 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+---
+
+Required Notice: Copyright (c) the estate of Nathan Okun. The underlying
+penetration mechanics and associated intellectual property — including the
+empirical formulas, algorithms, decision logic, historical data tables, and
+the original FACEHARD program flow, interaction process, and reproduced
+results/definition text — belong to the estate of Nathan Okun. No licence to
+that material is granted by Adrian Beale. Its use remains subject to the
+estate's terms, including its non-commercial restriction.
+
+Required Notice: Copyright (c) 2026 Adrian Beale. The Python implementation
+and its original additions — including Python-specific code, packaging,
+command-line interface, and additional features — are owned by Adrian Beale
+and licensed under the PolyForm Noncommercial License 1.0.0 above.
+
+This combined distribution is offered for non-commercial use only. Commercial
+use may require permission from both the estate of Nathan Okun (for the
+underlying material) and Adrian Beale (for the Python implementation and
+additions). See the NOTICE file for details.

facehard-1.0.0/NOTICE

@@ -0,0 +1,41 @@
+FACEHARD (Python port) — attribution and copyright notice
+==========================================================
+
+This package is an independent Python port of FACEHARD 8.0, a face-hardened
+naval-armour penetration program written by Nathan Okun in QuickBASIC.
+
+Underlying mechanics and original flow — Copyright (c) the estate of Nathan Okun
+-------------------------------------------------------------------------------
+The empirical penetration mechanics and related intellectual property — including
+the formulas, algorithms, ballistic-limit and post-impact decision logic,
+historical projectile/armour data tables, and the original FACEHARD program's
+flow, interaction process, and results/definition text — belong to the estate
+of Nathan Okun. Okun's material is published on NavWeaps under these terms:
+
+    "All material in this section of NavWeaps is copyrighted by the estate of
+     Nathan Okun and may not be used for commercial purposes without prior
+     written permission."
+    — http://www.navweaps.com/index_nathan/index_nathan.php
+
+This port reproduces that material (including Okun's own source-code comments,
+restored from the original FH80MAIN/FH80SBM1/FH80SBM2.BAS modules) for study and
+convenience. It makes NO claim of authorship over the mechanics, original flow,
+data, or text, and does not grant any rights in them beyond what the estate's
+terms allow.
+
+Python implementation and additions — Copyright (c) 2026 Adrian Beale
+-----------------------------------------------------------------------
+The Python-specific implementation and original additions — including the
+Python code, packaging, command-line interface, and additional features — are
+owned by Adrian Beale and licensed under the PolyForm Noncommercial License
+1.0.0 (see LICENSE). To keep the whole work consistent with the estate's terms,
+the port as a whole is offered for NONCOMMERCIAL use only.
+
+Commercial use of the underlying mechanics or original flow requires prior
+written permission from the estate of Nathan Okun. Commercial use of the
+Python implementation or additions requires permission from Adrian Beale. A
+use of this combined distribution may require permission from both rights
+holders.
+
+This is not legal advice. If you intend to redistribute or use this
+commercially, confirm the terms with the rights holders first.

facehard-1.0.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: facehard
+Version: 1.0.0
+Summary: Native Python port of Nathan Okun's FACEHARD 8.0 face-hardened naval armour penetration model, with a CLI.
+Author: Adrian Beale
+License: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/TinBane/facehard
+Project-URL: Repository, https://github.com/TinBane/facehard
+Keywords: naval,armour,penetration,ballistics,facehard,okun
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Games/Entertainment :: Simulation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# FACEHARD — native Python port, verbatim clone + CLI
+
+A faithful Python reimplementation of **FACEHARD 8.0**, Nathan Okun's face-hardened naval armour penetration program (QuickBASIC, 2018). It reproduces both the program's **numbers** and its **exact text output**, validated against the generated BASIC working oracle (`fh_oracle`) by differential fuzzing. Intentional oracle corrections are documented separately.
+
+Two ways to use it: a modern CLI (`facehard run/pen/list`) and a byte-faithful clone of the original interactive program (`facehard emulate`). Stdlib-only, pipx-installable.
+
+**Versions.** The package is versioned independently of the model: this is package **1.0.0**, reproducing Okun's **FACEHARD 8.0** (8 August 2018). `facehard.MODEL_VERSION` and `facehard --version` both report the model version alongside the package version.
+
+**Source.** Okun's original programs, papers and armour data are published at [NavWeaps — The Nathan Okun Collection](http://www.navweaps.com/index_nathan/index_nathan.php).
+
+## Install
+
+```bash
+pipx install facehard
+facehard --version
+```
+
+## CLI
+
+```
+facehard                     interactive wizard (modern menus)
+facehard emulate             the ORIGINAL FACEHARD interactive session, verbatim
+facehard run   [options]     one impact; --output narrative|limits|plug|metrics|json|all
+facehard pen   [options]     penetration thickness at a striking velocity
+facehard list  armors|nations|projectiles [--nation N]
+```
+
+`run`/`pen` scenario flags: `--armor 1-25 --nation 1-8 --proj N -d/--diameter -w/--weight -b/--body-weight -v/--velocity -o/--obliquity`; backing `--wood --cement --metal --metal-type --metal-plates`; nose loss `--remove {none,cap,windscreen,caphead} --windscreen-wt --caphead-wt`.  `run` also takes `-t/--thickness` (the plate to shoot); `pen` omits it because it *computes* the thickness defeated.
+
+## Library API
+
+```python
+from facehard import calc, results, render_results, penetration, names
+
+calc(armor=14, nation=1, proj=18, TA=16, D=16, WT=2700, WB=2048, OB=30).vltru
+results(armor=14, nation=1, proj=18, TA=12, D=16, WT=2700, WB=2048, OB=30, VS=2200)
+render_results(armor=14, nation=1, proj=18, TA=12, D=16, WT=2700, WB=2048,
+               OB=30, VS=2200, show_limits=True)          # verbatim BASIC text
+penetration(armor=14, nation=1, proj=18, D=16, WT=2700, WB=2048, V=2500, OB=0)  # 29.5 in
+```
+
+Every numeric menu choice also has a named `IntEnum` — drop-in for the plain numbers, which stay valid everywhere:
+
+```python
+from facehard import penetration, Armor, Nation, USProjectile, projectiles
+
+Nation.UK == 2                                            # original menu numbers, unchanged
+penetration(armor=Armor.BRITISH_CA, nation=Nation.USA,
+            proj=USProjectile.APC_6IN_MK35_16IN_MK8,      # 16-in Mk 8 (IOWA)
+            D=16, WT=2700, WB=2048, V=2500, OB=0)
+
+projectiles(Nation.JAPAN).APC_TYPE91                      # per-nation projectile menus
+Armor.JAPANESE_VH.menu_text                               # the original menu line
+```
+
+`Nation`, `Armor`, `BackingMetal` (the `metal_type` parameter), and one projectile enum per nation (`USProjectile`, `BritishProjectile`, `GermanProjectile`, `FrenchProjectile`, `ItalianProjectile`, `JapaneseProjectile`, `AustroHungarianProjectile`, `RussianProjectile`). The short names summarise menu lines that often cover several marks — `member.menu_text` is authoritative.
+
+All of `calc`/`results`/`render_results` accept backing, nose-covering loss (`remove`, `windscreen_wt`, `caphead_wt`), and manual armour overrides (`armor_overrides={"Q": 0.8, "UB": 60, ...}` for UB/Q/QDAM/CARTWL/CMPND/THNCHL/SOFTSHAT/THKTHN).
+
+## Coverage — the whole program
+
+| Layer | Status |
+|-------|--------|
+| Ballistic limits (N1–N4, H1–H4) | ported, 100% vs BASIC |
+| Post-impact results (outcome, exit angle, plug weights, remaining velocity, effective BL) | ported, 100% |
+| Verbatim results narrative (`RESULTSPRINT` + damage flags) | ported, word-for-word |
+| Backing (wood/cement/metal) & nose-covering loss (decapping) | ported, 100% |
+| Manual armour-parameter overrides ("modify parameters" screen) | ported, applies + verbatim |
+| Interactive shell (menus, info pages, prompts, re-run state) | ported, verbatim (`facehard emulate`) |
+
+Not reproduced: nothing functional — only the DOS graphics-mode screen clears (cosmetic) differ.
+
+## Fidelity — how close to the BASIC?
+
+`precision_audit.py` (1500 fuzzed examples, deterministic):
+
+- **Zero velocity deviations** across 6,818 ballistic-limit and post-impact velocity comparisons.
+- Exit angles agree exactly in the retained 10,000-case differential campaign.
+- The remaining differences are BASIC display rounding of plug weights to one decimal place (maximum 0.05 lb).
+
+The generated working oracle uses double precision and contains the documented post-impact-limit correction in `ORACLE_PATCHES.md`.
+
+Verbatim-text fuzzers confirm the same at the string level: `fuzz_narrative.py` 99.97% of result lines, `fuzz_emulate.py` 99.98% of full-session lines, `fuzz_override.py` 100% of override sessions — residual diffs are those same sub-unit display roundings.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `facehard/` | installable package: `model.py`, `emulate.py`, `cli.py`, `names.py` |
+| `fh_oracle` | compiled BASIC oracle; rebuild via `build_qb64.py` + QB64-PE |
+| `facehard.bas` / `build_qb64.py` | the merged BASIC and its generator |
+| `ORACLE_PATCHES.md` | intentional model corrections applied to the generated oracle |
+| `facehard_run.py` | drives `fh_oracle`, parses its output |
+| `facehard_native.py` | back-compat shim → `facehard.model` |
+| `validate_native.py` / `validate_results.py` | limit & post-impact sweeps vs BASIC |
+| `precision_audit.py` | exact deviation audit (identical / off-by-1 / ≥2) |
+| `fuzz_native/narrative/emulate/override.py` | differential fuzzers |
+| `reproduce_table4_native.py` | reproduces the published comparison table, pure Python |
+
+## Licence
+
+Not open-source. The penetration mechanics and associated IP — including the
+formulas, decision logic, data tables, and original FACEHARD program flow and
+text — belong to the estate of Nathan Okun and, per [NavWeaps](http://www.navweaps.com/index_nathan/index_nathan.php)' terms, may not be
+used commercially without prior written permission. The Python implementation
+and its original additions are Copyright © 2026 Adrian Beale and are released
+under the PolyForm Noncommercial License 1.0.0. The combined distribution is
+for **noncommercial use only**; commercial use may require permission from both
+rights holders. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

facehard-1.0.0/README.md

@@ -0,0 +1,109 @@
+# FACEHARD — native Python port, verbatim clone + CLI
+
+A faithful Python reimplementation of **FACEHARD 8.0**, Nathan Okun's face-hardened naval armour penetration program (QuickBASIC, 2018). It reproduces both the program's **numbers** and its **exact text output**, validated against the generated BASIC working oracle (`fh_oracle`) by differential fuzzing. Intentional oracle corrections are documented separately.
+
+Two ways to use it: a modern CLI (`facehard run/pen/list`) and a byte-faithful clone of the original interactive program (`facehard emulate`). Stdlib-only, pipx-installable.
+
+**Versions.** The package is versioned independently of the model: this is package **1.0.0**, reproducing Okun's **FACEHARD 8.0** (8 August 2018). `facehard.MODEL_VERSION` and `facehard --version` both report the model version alongside the package version.
+
+**Source.** Okun's original programs, papers and armour data are published at [NavWeaps — The Nathan Okun Collection](http://www.navweaps.com/index_nathan/index_nathan.php).
+
+## Install
+
+```bash
+pipx install facehard
+facehard --version
+```
+
+## CLI
+
+```
+facehard                     interactive wizard (modern menus)
+facehard emulate             the ORIGINAL FACEHARD interactive session, verbatim
+facehard run   [options]     one impact; --output narrative|limits|plug|metrics|json|all
+facehard pen   [options]     penetration thickness at a striking velocity
+facehard list  armors|nations|projectiles [--nation N]
+```
+
+`run`/`pen` scenario flags: `--armor 1-25 --nation 1-8 --proj N -d/--diameter -w/--weight -b/--body-weight -v/--velocity -o/--obliquity`; backing `--wood --cement --metal --metal-type --metal-plates`; nose loss `--remove {none,cap,windscreen,caphead} --windscreen-wt --caphead-wt`.  `run` also takes `-t/--thickness` (the plate to shoot); `pen` omits it because it *computes* the thickness defeated.
+
+## Library API
+
+```python
+from facehard import calc, results, render_results, penetration, names
+
+calc(armor=14, nation=1, proj=18, TA=16, D=16, WT=2700, WB=2048, OB=30).vltru
+results(armor=14, nation=1, proj=18, TA=12, D=16, WT=2700, WB=2048, OB=30, VS=2200)
+render_results(armor=14, nation=1, proj=18, TA=12, D=16, WT=2700, WB=2048,
+               OB=30, VS=2200, show_limits=True)          # verbatim BASIC text
+penetration(armor=14, nation=1, proj=18, D=16, WT=2700, WB=2048, V=2500, OB=0)  # 29.5 in
+```
+
+Every numeric menu choice also has a named `IntEnum` — drop-in for the plain numbers, which stay valid everywhere:
+
+```python
+from facehard import penetration, Armor, Nation, USProjectile, projectiles
+
+Nation.UK == 2                                            # original menu numbers, unchanged
+penetration(armor=Armor.BRITISH_CA, nation=Nation.USA,
+            proj=USProjectile.APC_6IN_MK35_16IN_MK8,      # 16-in Mk 8 (IOWA)
+            D=16, WT=2700, WB=2048, V=2500, OB=0)
+
+projectiles(Nation.JAPAN).APC_TYPE91                      # per-nation projectile menus
+Armor.JAPANESE_VH.menu_text                               # the original menu line
+```
+
+`Nation`, `Armor`, `BackingMetal` (the `metal_type` parameter), and one projectile enum per nation (`USProjectile`, `BritishProjectile`, `GermanProjectile`, `FrenchProjectile`, `ItalianProjectile`, `JapaneseProjectile`, `AustroHungarianProjectile`, `RussianProjectile`). The short names summarise menu lines that often cover several marks — `member.menu_text` is authoritative.
+
+All of `calc`/`results`/`render_results` accept backing, nose-covering loss (`remove`, `windscreen_wt`, `caphead_wt`), and manual armour overrides (`armor_overrides={"Q": 0.8, "UB": 60, ...}` for UB/Q/QDAM/CARTWL/CMPND/THNCHL/SOFTSHAT/THKTHN).
+
+## Coverage — the whole program
+
+| Layer | Status |
+|-------|--------|
+| Ballistic limits (N1–N4, H1–H4) | ported, 100% vs BASIC |
+| Post-impact results (outcome, exit angle, plug weights, remaining velocity, effective BL) | ported, 100% |
+| Verbatim results narrative (`RESULTSPRINT` + damage flags) | ported, word-for-word |
+| Backing (wood/cement/metal) & nose-covering loss (decapping) | ported, 100% |
+| Manual armour-parameter overrides ("modify parameters" screen) | ported, applies + verbatim |
+| Interactive shell (menus, info pages, prompts, re-run state) | ported, verbatim (`facehard emulate`) |
+
+Not reproduced: nothing functional — only the DOS graphics-mode screen clears (cosmetic) differ.
+
+## Fidelity — how close to the BASIC?
+
+`precision_audit.py` (1500 fuzzed examples, deterministic):
+
+- **Zero velocity deviations** across 6,818 ballistic-limit and post-impact velocity comparisons.
+- Exit angles agree exactly in the retained 10,000-case differential campaign.
+- The remaining differences are BASIC display rounding of plug weights to one decimal place (maximum 0.05 lb).
+
+The generated working oracle uses double precision and contains the documented post-impact-limit correction in `ORACLE_PATCHES.md`.
+
+Verbatim-text fuzzers confirm the same at the string level: `fuzz_narrative.py` 99.97% of result lines, `fuzz_emulate.py` 99.98% of full-session lines, `fuzz_override.py` 100% of override sessions — residual diffs are those same sub-unit display roundings.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `facehard/` | installable package: `model.py`, `emulate.py`, `cli.py`, `names.py` |
+| `fh_oracle` | compiled BASIC oracle; rebuild via `build_qb64.py` + QB64-PE |
+| `facehard.bas` / `build_qb64.py` | the merged BASIC and its generator |
+| `ORACLE_PATCHES.md` | intentional model corrections applied to the generated oracle |
+| `facehard_run.py` | drives `fh_oracle`, parses its output |
+| `facehard_native.py` | back-compat shim → `facehard.model` |
+| `validate_native.py` / `validate_results.py` | limit & post-impact sweeps vs BASIC |
+| `precision_audit.py` | exact deviation audit (identical / off-by-1 / ≥2) |
+| `fuzz_native/narrative/emulate/override.py` | differential fuzzers |
+| `reproduce_table4_native.py` | reproduces the published comparison table, pure Python |
+
+## Licence
+
+Not open-source. The penetration mechanics and associated IP — including the
+formulas, decision logic, data tables, and original FACEHARD program flow and
+text — belong to the estate of Nathan Okun and, per [NavWeaps](http://www.navweaps.com/index_nathan/index_nathan.php)' terms, may not be
+used commercially without prior written permission. The Python implementation
+and its original additions are Copyright © 2026 Adrian Beale and are released
+under the PolyForm Noncommercial License 1.0.0. The combined distribution is
+for **noncommercial use only**; commercial use may require permission from both
+rights holders. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

facehard-1.0.0/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",
+]