bfflearn 0.1.0.dev1__tar.gz → 0.1.0.dev2__tar.gz

{bfflearn-0.1.0.dev1 → bfflearn-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bfflearn
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: Bayesian workflows for fixed-charge molecular force fields
 Author-email: Vojtech Kostal <vojtakostal8@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -746,6 +746,12 @@ The public CLI is centered around six workflows:
 - `bff learn`
 - `bff validate`
 
+Examples can be fetched on demand with:
+
+```bash
+bff examples
+```
+
 Documentation lives under [docs/](docs/) and is intended to be published with
 MkDocs on GitHub Pages.
 
@@ -795,6 +801,20 @@ Then install BFF from PyPI:
 pip install bfflearn
 ```
 
+If you want the exact code used for the paper, do not install `v0.0.1`
+directly through a `pip` Git URL. That archived tag predates the packaging
+cleanup. Instead, clone the repository, check out the archived tag, and follow
+the `README.md` and `environment.yaml` shipped with that snapshot:
+
+```bash
+git clone https://github.com/vojtechkostal/BayesicForceFields.git
+cd BayesicForceFields
+git checkout v0.0.1
+```
+
+Use `v0.0.1` for exact reproduction of the published paper data. The current
+`bfflearn` release line is the post-paper refactored workflow.
+
 External tools are still required for full workflows:
 
 - [Gromacs](https://www.gromacs.org) for `prepare`, `simulate`, and `validate`
@@ -856,6 +876,13 @@ Two notebooks are included in the example:
 - [07-visualize/visualize.ipynb](examples/acetate/07-visualize/visualize.ipynb)
   focuses on plotting and inspection only.
 
+If you installed BFF from PyPI and want the example tree locally, run:
+
+```bash
+bff examples
+cd examples/acetate
+```
+
 ## Repository Layout
 
 - [bff/](bff/) contains the package code.

{bfflearn-0.1.0.dev1 → bfflearn-0.1.0.dev2}/README.md

@@ -21,6 +21,12 @@ The public CLI is centered around six workflows:
 - `bff learn`
 - `bff validate`
 
+Examples can be fetched on demand with:
+
+```bash
+bff examples
+```
+
 Documentation lives under [docs/](docs/) and is intended to be published with
 MkDocs on GitHub Pages.
 
@@ -70,6 +76,20 @@ Then install BFF from PyPI:
 pip install bfflearn
 ```
 
+If you want the exact code used for the paper, do not install `v0.0.1`
+directly through a `pip` Git URL. That archived tag predates the packaging
+cleanup. Instead, clone the repository, check out the archived tag, and follow
+the `README.md` and `environment.yaml` shipped with that snapshot:
+
+```bash
+git clone https://github.com/vojtechkostal/BayesicForceFields.git
+cd BayesicForceFields
+git checkout v0.0.1
+```
+
+Use `v0.0.1` for exact reproduction of the published paper data. The current
+`bfflearn` release line is the post-paper refactored workflow.
+
 External tools are still required for full workflows:
 
 - [Gromacs](https://www.gromacs.org) for `prepare`, `simulate`, and `validate`
@@ -131,6 +151,13 @@ Two notebooks are included in the example:
 - [07-visualize/visualize.ipynb](examples/acetate/07-visualize/visualize.ipynb)
   focuses on plotting and inspection only.
 
+If you installed BFF from PyPI and want the example tree locally, run:
+
+```bash
+bff examples
+cd examples/acetate
+```
+
 ## Repository Layout
 
 - [bff/](bff/) contains the package code.

{bfflearn-0.1.0.dev1 → bfflearn-0.1.0.dev2}/bff/__init__.py

@@ -2,7 +2,7 @@
 
 from importlib import import_module
 
-__version__ = "0.1.0.dev1"
+__version__ = "0.1.0.dev2"
 
 __all__ = [
     "bayes",

{bfflearn-0.1.0.dev1 → bfflearn-0.1.0.dev2}/bff/cli.py

@@ -20,6 +20,7 @@ WORKFLOW_COMMANDS = (
     "train",
     "learn",
     "validate",
+    "examples",
 )
 
 _COMPLETION_ACTIVATE = f"""# Managed automatically by Bayesic Force Fields.
@@ -172,6 +173,45 @@ def version() -> None:
     typer.echo(f"BayesicForceFields version: {version_str}")
 
 
+@app.command()
+def examples(
+    output_dir: Path = typer.Option(
+        Path("examples"),
+        "--output-dir",
+        file_okay=False,
+        dir_okay=True,
+        writable=True,
+        resolve_path=False,
+        help="Directory to write the example tree into.",
+    ),
+    ref: str | None = typer.Option(
+        None,
+        "--ref",
+        help="Git ref to download examples from. Defaults to the installed tag.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Replace the output directory if it already exists.",
+    ),
+) -> None:
+    """
+    Download or copy all repository examples.
+    """
+    from bff.workflows.examples import fetch_examples
+
+    try:
+        examples_dir, source = fetch_examples(output_dir, ref=ref, force=force)
+    except FileExistsError as exc:
+        raise typer.BadParameter(str(exc), param_hint="output_dir") from exc
+    except RuntimeError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(f"Examples written to: {examples_dir}")
+    typer.echo(f"Source: {source}")
+
+
 @app.command()
 def prepare(fn_config: Path = config_argument()) -> None:
     """

bfflearn-0.1.0.dev2/bff/workflows/examples.py

@@ -0,0 +1,132 @@
+"""Download or copy example workflows for local use."""
+
+from __future__ import annotations
+
+import shutil
+import tarfile
+import tempfile
+from importlib import metadata
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .. import __version__
+
+_REPOSITORY = "https://github.com/vojtechkostal/BayesicForceFields"
+_ARCHIVE_API = "https://api.github.com/repos/vojtechkostal/BayesicForceFields/tarball"
+
+
+def _installed_version() -> str:
+    try:
+        return metadata.version("bfflearn")
+    except metadata.PackageNotFoundError:
+        return __version__
+
+
+def _default_ref() -> str:
+    return f"v{_installed_version()}"
+
+
+def _local_examples_dir() -> Path | None:
+    repo_root = Path(__file__).resolve().parents[2]
+    examples_dir = repo_root / "examples"
+    if examples_dir.is_dir() and (repo_root / ".git").exists():
+        return examples_dir
+    return None
+
+
+def _prepare_output_dir(output_dir: Path, *, force: bool) -> None:
+    if output_dir.exists():
+        if not force:
+            raise FileExistsError(
+                f"Output directory already exists: {output_dir}. "
+                "Use --force to replace it."
+            )
+        shutil.rmtree(output_dir)
+
+
+def _copy_local_examples(source_dir: Path, output_dir: Path) -> Path:
+    shutil.copytree(source_dir, output_dir)
+    return output_dir
+
+
+def _download_archive(ref: str, archive_path: Path) -> None:
+    request = Request(
+        f"{_ARCHIVE_API}/{ref}",
+        headers={"User-Agent": "bfflearn-example-fetcher"},
+    )
+    try:
+        with urlopen(request) as response, archive_path.open("wb") as out_file:
+            shutil.copyfileobj(response, out_file)
+    except HTTPError as exc:
+        raise RuntimeError(
+            f"Could not download examples for ref '{ref}' from {_REPOSITORY}."
+        ) from exc
+    except URLError as exc:
+        raise RuntimeError(
+            "Could not reach GitHub to download examples. "
+            "Check your internet connection and try again."
+        ) from exc
+
+
+def _extract_examples_archive(archive_path: Path, output_dir: Path) -> Path:
+    files_written = 0
+    with tarfile.open(archive_path, "r:gz") as archive:
+        for member in archive.getmembers():
+            parts = Path(member.name).parts
+            if len(parts) < 3 or parts[1] != "examples":
+                continue
+
+            relative_path = Path(*parts[2:])
+            target_path = output_dir / relative_path
+
+            if member.isdir():
+                target_path.mkdir(parents=True, exist_ok=True)
+                continue
+
+            if not member.isfile():
+                continue
+
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            extracted = archive.extractfile(member)
+            if extracted is None:
+                continue
+            with extracted, target_path.open("wb") as out_file:
+                shutil.copyfileobj(extracted, out_file)
+            files_written += 1
+
+    if files_written == 0:
+        raise RuntimeError("Downloaded archive did not contain an examples directory.")
+
+    return output_dir
+
+
+def fetch_examples(
+    output_dir: Path,
+    *,
+    ref: str | None = None,
+    force: bool = False,
+) -> tuple[Path, str]:
+    """
+    Fetch all repository examples into ``output_dir``.
+
+    If running from a source checkout, examples are copied from the local
+    repository. Otherwise, the example tree is downloaded from GitHub for the
+    requested ref or the installed package version tag.
+    """
+
+    output_dir = output_dir.expanduser().resolve()
+    _prepare_output_dir(output_dir, force=force)
+
+    local_examples = _local_examples_dir()
+    if local_examples is not None:
+        return _copy_local_examples(local_examples, output_dir), "local checkout"
+
+    resolved_ref = ref or _default_ref()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        archive_path = Path(tmpdir) / "examples.tar.gz"
+        _download_archive(resolved_ref, archive_path)
+        return (
+            _extract_examples_archive(archive_path, output_dir),
+            f"{_REPOSITORY} @ {resolved_ref}",
+        )

{bfflearn-0.1.0.dev1 → bfflearn-0.1.0.dev2}/bfflearn.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bfflearn
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: Bayesian workflows for fixed-charge molecular force fields
 Author-email: Vojtech Kostal <vojtakostal8@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -746,6 +746,12 @@ The public CLI is centered around six workflows:
 - `bff learn`
 - `bff validate`
 
+Examples can be fetched on demand with:
+
+```bash
+bff examples
+```
+
 Documentation lives under [docs/](docs/) and is intended to be published with
 MkDocs on GitHub Pages.
 
@@ -795,6 +801,20 @@ Then install BFF from PyPI:
 pip install bfflearn
 ```
 
+If you want the exact code used for the paper, do not install `v0.0.1`
+directly through a `pip` Git URL. That archived tag predates the packaging
+cleanup. Instead, clone the repository, check out the archived tag, and follow
+the `README.md` and `environment.yaml` shipped with that snapshot:
+
+```bash
+git clone https://github.com/vojtechkostal/BayesicForceFields.git
+cd BayesicForceFields
+git checkout v0.0.1
+```
+
+Use `v0.0.1` for exact reproduction of the published paper data. The current
+`bfflearn` release line is the post-paper refactored workflow.
+
 External tools are still required for full workflows:
 
 - [Gromacs](https://www.gromacs.org) for `prepare`, `simulate`, and `validate`
@@ -856,6 +876,13 @@ Two notebooks are included in the example:
 - [07-visualize/visualize.ipynb](examples/acetate/07-visualize/visualize.ipynb)
   focuses on plotting and inspection only.
 
+If you installed BFF from PyPI and want the example tree locally, run:
+
+```bash
+bff examples
+cd examples/acetate
+```
+
 ## Repository Layout
 
 - [bff/](bff/) contains the package code.

{bfflearn-0.1.0.dev1 → bfflearn-0.1.0.dev2}/bfflearn.egg-info/SOURCES.txt

@@ -42,6 +42,7 @@ bff/qoi/rdf.py
 bff/qoi/routines.py
 bff/workflows/__init__.py
 bff/workflows/configs.py
+bff/workflows/examples.py
 bff/workflows/learn.py
 bff/workflows/md.py
 bff/workflows/prepare.py

{bfflearn-0.1.0.dev1 → bfflearn-0.1.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bfflearn"
-version = "0.1.0.dev1"
+version = "0.1.0.dev2"
 description = "Bayesian workflows for fixed-charge molecular force fields"
 authors = [
   { name="Vojtech Kostal", email="vojtakostal8@gmail.com" }