update with uv

Author: EvenSol

.github/workflows/generate-stubs.yml

@@ -40,8 +40,12 @@ jobs:
         run: |
           uv run python scripts/generate_stubs.py
 
-      - name: Commit updated stubs
+      - name: Generate offline API manifest
+        run: |
+          uv run python scripts/generate_api_manifest.py
+
+      - name: Commit updated stubs and manifest
         uses: stefanzweifel/git-auto-commit-action@v7
         with:
-          commit_message: "chore: regenerate Java stubs"
-          file_pattern: "src/jneqsim/**/*.pyi"
+          commit_message: "chore: regenerate Java stubs and API manifest"
+          file_pattern: "src/jneqsim-stubs/**/*.pyi src/neqsim/data/neqsim_api.json.gz"

README.md

@@ -217,6 +217,84 @@ print(f"Compressor power: {comp.getPower()/1e6:.2f} MW")
 | Configuration-driven design | ProcessBuilder |
 | Advanced Java features | Direct Java access |
 
+> **The `jneqsim` gateway is the first-class path for the long tail.** Only a
+> curated subset of NeqSim's ~2500 Java classes has hand-written Python
+> wrappers. Mechanical design, safety, field development, automation, and most
+> specialized equipment are used directly through `jneqsim` — no wrapper needed.
+
+---
+
+## 🔎 Discovering the Full API
+
+Direct `jneqsim` access is powerful but hard to explore (a `JPackage` has no
+autocomplete). The `neqsim.discovery` module scans the API at runtime so you can
+list, search, and inspect every class from Python:
+
+```python
+from neqsim import discovery
+
+discovery.list_equipment()                 # every process-equipment class
+discovery.list_packages('process')         # sub-packages of neqsim.process
+discovery.find_classes('scrubber')         # search the whole API by keyword
+print(discovery.describe('Compressor'))    # constructors + methods via reflection
+
+Compressor = discovery.get_class('Compressor')   # JClass by simple or full name
+```
+
+For IDE autocomplete and type checking across the entire Java API, generate type
+stubs (already packaged as `jneqsim-stubs`, regenerate with
+`python scripts/generate_stubs.py`) and point your editor at `src`. An offline
+API manifest (`python scripts/generate_api_manifest.py`) lets `discovery` list,
+search, and describe classes instantly and JVM-free.
+
+### Typed, validated flowsheets (optional)
+
+With `pip install "neqsim[schema]"` you can build flowsheets from typed
+[pydantic](https://docs.pydantic.dev) models — autocomplete and validation
+*before* the JVM runs:
+
+```python
+from neqsim.process.schema import ProcessModel, Fluid, Unit
+
+model = ProcessModel(
+    fluid=Fluid(eos="srk", components={"methane": 0.9, "ethane": 0.1}),
+    process=[
+        Unit(type="Stream", name="feed",
+             properties={"flowRate": [50000.0, "kg/hr"], "pressure": [50.0, "bara"]}),
+        Unit(type="Separator", name="HP Sep", inlet="feed"),
+    ],
+)
+result = model.run()           # validates, builds, and runs
+```
+
+### Component-name helpers
+
+```python
+from neqsim.thermo.components import find_components, suggest_component
+find_components("glycol")            # search the component database
+suggest_component("methan")          # ['methane', 'methanol', ...] — catch typos
+```
+
+### Rich Jupyter display
+
+Streams and processes render as HTML tables in notebooks automatically (just
+display the object) — no extra call needed.
+
+### Results to pandas
+
+One helper turns any process into a tidy stream table (works for every
+equipment type, because it walks the flowsheet's streams):
+
+```python
+from neqsim.process import stream_table, equipment_table, runProcess
+
+runProcess()
+stream_table()        # one row per stream: flow, T, P, phases, density, molar mass
+equipment_table()     # one row per unit: name, type, inlet/outlet counts
+
+stream_table(my_process)   # or pass an explicit ProcessSystem / ProcessContext
+```
+
 ---
 
 ## 🧪 PVT Simulation

pyproject.toml

@@ -28,6 +28,9 @@ interactive = [
     "jupyter>=1.0.0,<2",
     "tabulate>=0.9.0,<0.10",
 ]
+schema = [
+    "pydantic>=2.0,<3",
+]
 
 [project.urls]
 Homepage = "https://github.com/Equinor/neqsim-python"
@@ -54,6 +57,7 @@ source-include = [
     "src/jpype-stubs/**",
     "src/neqsim/**/*.pyi",
     "src/neqsim/py.typed",
+    "src/neqsim/data/neqsim_api.json.gz",
 ]
 
 [build-system]

scripts/generate_api_manifest.py

@@ -0,0 +1,138 @@
+"""Generate the offline NeqSim API manifest consumed by ``neqsim.discovery``.
+
+Runs once at release time. It reflects the whole Java API (via ``neqsim.discovery``
+live reflection) and writes ``src/neqsim/data/neqsim_api.json`` containing every
+class with its constructors and public method names. Shipping that file makes
+``discovery.list_classes`` / ``find_classes`` / ``describe`` work instantly and
+JVM-free for end users, and it can drive a docs site.
+
+Usage
+-----
+    python scripts/generate_api_manifest.py [--out PATH] [--packages neqsim ...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_SRC = _REPO_ROOT / "src"
+if _SRC.is_dir():
+    sys.path.insert(0, str(_SRC))
+
+from neqsim import discovery  # noqa: E402
+
+
+def _class_entry(fqcn: str) -> Dict[str, List[str]]:
+    """Build the manifest entry (constructors + methods) for one class.
+
+    Args:
+        fqcn: Fully-qualified Java class name.
+
+    Returns:
+        A dict with ``constructors`` and ``methods`` lists (possibly empty).
+    """
+    constructors: List[str] = []
+    methods: List[str] = []
+    try:
+        java_class = discovery.get_class(fqcn).class_
+        constructors = sorted(
+            discovery._simplify_signature(str(c)) for c in java_class.getConstructors()
+        )
+        method_names = set()
+        for m in java_class.getMethods():
+            name = str(m.getName())
+            if name.isidentifier():
+                method_names.add(name)
+        methods = sorted(method_names)
+    except Exception:
+        pass
+    return {"constructors": constructors, "methods": methods}
+
+
+def _detect_version() -> str:
+    """Return the NeqSim jar version if derivable, else ``"unknown"``."""
+    try:
+        for entry in discovery._classpath_entries():
+            name = Path(entry).name
+            if name.startswith("neqsim-") and name.endswith(".jar"):
+                return name[len("neqsim-") : -len(".jar")]
+    except Exception:
+        pass
+    return "unknown"
+
+
+def generate(out_path: Path, packages: List[str]) -> int:
+    """Generate the manifest for the requested packages.
+
+    Args:
+        out_path: Destination JSON file.
+        packages: Package prefixes to include.
+
+    Returns:
+        The number of classes written.
+    """
+    class_names: List[str] = []
+    for prefix in packages:
+        class_names.extend(discovery.list_classes(prefix, recursive=True))
+    class_names = sorted(set(class_names))
+
+    classes: Dict[str, Dict[str, List[str]]] = {}
+    for fqcn in class_names:
+        classes[fqcn] = _class_entry(fqcn)
+
+    manifest = {
+        "schema": "neqsim-api-manifest/1.0",
+        "version": _detect_version(),
+        "generated": datetime.now(timezone.utc).isoformat(),
+        "class_count": len(classes),
+        "classes": classes,
+    }
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(manifest, indent=1, sort_keys=True)
+    if out_path.suffix == ".gz":
+        with gzip.open(out_path, "wt", encoding="utf-8") as handle:
+            handle.write(payload)
+    else:
+        with open(out_path, "w", encoding="utf-8") as handle:
+            handle.write(payload)
+    return len(classes)
+
+
+def main(argv: List[str] | None = None) -> int:
+    """CLI entry point.
+
+    Args:
+        argv: Optional argument list (defaults to ``sys.argv``).
+
+    Returns:
+        Process exit code.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--out",
+        default=str(_SRC / "neqsim" / "data" / "neqsim_api.json.gz"),
+        help="Output path for the manifest JSON (use .gz to gzip).",
+    )
+    parser.add_argument(
+        "--packages",
+        nargs="*",
+        default=["neqsim"],
+        help="Package prefixes to include (default: the whole neqsim tree).",
+    )
+    args = parser.parse_args(argv)
+
+    count = generate(Path(args.out), args.packages)
+    print(f"Wrote manifest with {count} classes to {args.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/generate_component_literals.py

@@ -0,0 +1,108 @@
+"""Generate a ``Literal`` type of NeqSim component names for editor autocomplete.
+
+Produces two files under ``src/neqsim/thermo``:
+
+* ``component_names.py`` - runtime module exposing ``COMPONENTS`` (a tuple) and
+  ``ComponentName`` (``str`` at runtime).
+* ``component_names.pyi`` - type stub declaring ``ComponentName`` as a
+  ``Literal[...]`` of every known component, so editors autocomplete and type
+  checkers flag typos when a function is annotated ``name: ComponentName``.
+
+Run at release time (component database rarely changes)::
+
+    python scripts/generate_component_literals.py
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_SRC = _REPO_ROOT / "src"
+if _SRC.is_dir():
+    sys.path.insert(0, str(_SRC))
+
+
+def _component_names() -> List[str]:
+    """Return all NeqSim component names via the runtime helper.
+
+    Returns:
+        A sorted list of component names.
+    """
+    from neqsim.thermo.components import list_components
+
+    return list_components()
+
+
+def _render_pyi(names: List[str]) -> str:
+    """Render the ``.pyi`` stub text.
+
+    Args:
+        names: Component names.
+
+    Returns:
+        The stub file contents.
+    """
+    literals = ",\n    ".join(repr(n) for n in names)
+    return (
+        "# Auto-generated by scripts/generate_component_literals.py - do not edit.\n"
+        "from typing import Literal, Tuple\n\n"
+        "COMPONENTS: Tuple[str, ...]\n\n"
+        "ComponentName = Literal[\n    "
+        f"{literals},\n]\n"
+    )
+
+
+def _render_py(names: List[str]) -> str:
+    """Render the runtime ``.py`` module text.
+
+    Args:
+        names: Component names.
+
+    Returns:
+        The module file contents.
+    """
+    joined = ",\n    ".join(repr(n) for n in names)
+    header = (
+        '"""Auto-generated NeqSim component names.\n\n'
+        "See scripts/generate_component_literals.py. ComponentName is a plain\n"
+        "``str`` at runtime; the companion .pyi makes it a ``Literal`` for type\n"
+        'checkers and editors.\n"""\n\n'
+    )
+    return header + "ComponentName = str\n\n" + f"COMPONENTS = (\n    {joined},\n)\n"
+
+
+def main(argv: List[str] | None = None) -> int:
+    """CLI entry point.
+
+    Args:
+        argv: Optional argument list.
+
+    Returns:
+        Process exit code.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--out-dir",
+        default=str(_SRC / "neqsim" / "thermo"),
+        help="Directory to write component_names.py/.pyi into.",
+    )
+    args = parser.parse_args(argv)
+
+    names = _component_names()
+    if not names:
+        print("No component names found (is the NeqSim jar available?)", file=sys.stderr)
+        return 1
+
+    out_dir = Path(args.out_dir)
+    (out_dir / "component_names.py").write_text(_render_py(names), encoding="utf-8")
+    (out_dir / "component_names.pyi").write_text(_render_pyi(names), encoding="utf-8")
+    print(f"Wrote {len(names)} component names to {out_dir}/component_names.py[i]")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())