From 43a83fe7c7d7ec7f4c2361bfe46fab1d44fcb86a Mon Sep 17 00:00:00 2001 From: Davin Potts Date: Fri, 13 Nov 2026 16:20:12 -0600 Subject: [PATCH 1/6] Added intended DragonHPC notebooks overwriting placeholders, updated refs in syllabi and READMEs, added solutions for test. --- README.md | 3 +- brev/requirements.txt | 2 +- .../12__dragonhpc_cuphoton__intro.ipynb | 718 ++++++++ ...=> 13__dragonhpc_cuphoton__workflow.ipynb} | 26 +- .../distributed/images/ddict_overview.png | Bin 0 -> 65569 bytes ..._dragonhpc_cuphoton__intro__SOLUTION.ipynb | 882 +++++++++ ...agonhpc_cuphoton__workflow__SOLUTION.ipynb | 1619 +++++++++++++++++ notebooks/syllabi/sc26__8_hours.ipynb | 6 +- test/test_packages.py | 2 +- 9 files changed, 3239 insertions(+), 19 deletions(-) create mode 100644 notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb rename notebooks/distributed/{12__dragonhpc_cuphoton__workflow.ipynb => 13__dragonhpc_cuphoton__workflow.ipynb} (99%) create mode 100644 notebooks/distributed/images/ddict_overview.png create mode 100644 notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb create mode 100644 notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb diff --git a/README.md b/README.md index ccd31d1..1f722d5 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,8 @@ In this tutorial we will cover: - Programming models in Python for GPU applications: array expressions, fusion, library iterators, kernel authoring, and interoperability with CUDA C++ kernels. - Reading an application's profile with Nsight Systems and Nsight Compute. - Case studies of horizontal Python and C++ integration in domain sciences such as cancer research and high energy physics. -- cuPhoton and DragonHPC (placeholder). +- DragonHPC fundamentals enabling `multiprocessing` to scale across HPC multi-node resources. +- cuPhoton astronomical image processing workflows orchestrated using DragonHPC. Attendees are expected to have general knowledge of HPC and Python programming. Some familiarity with NumPy and C/C++ is helpful but not required. The outline and the notebook list are in diff --git a/brev/requirements.txt b/brev/requirements.txt index 8b4fea6..cd9571d 100644 --- a/brev/requirements.txt +++ b/brev/requirements.txt @@ -39,7 +39,7 @@ nsightful[notebook] @ git+https://github.com/brycelelbach/nsightful.git@a4198940 # Distributed computing. The mpi4py wheel loads the system OpenMPI. mpi4py == 4.1.2 -dragonhpc == 0.14.2 +dragonhpc == 0.15.0 # Runtime and notebook execution utilities psutil == 7.2.2 diff --git a/notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb b/notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb new file mode 100644 index 0000000..9f79f9a --- /dev/null +++ b/notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb @@ -0,0 +1,718 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0122416a", + "metadata": {}, + "source": [ + "# SC26 DragonHPC Multiprocessing, Native, and DDict Tutorial\n", + "\n", + "**Estimated time:** ~30-45 minutes \n", + "**Format:** 6 short exercises - each has a problem and a hidden answer you can reveal.\n", + "\n", + "---\n", + "\n", + "## What you will learn\n", + "\n", + "This notebook introduces Python multiprocessing with DragonHPC for single-node\n", + "and multi-node runs. You will practice how to:\n", + "\n", + "- launch processes\n", + "- synchronize worker execution\n", + "- communicate data between processes\n", + "- observe process placement across nodes\n", + "\n", + "The exercises are beginner friendly, while also connecting to concepts that\n", + "intermediate and advanced users already know from Python multiprocessing.\n", + "\n", + "---\n", + "\n", + "## Setup - run this first!\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fc68fa9d-cd2d-4056-94df-040ecd062dbe", + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "import os\n", + "import socket\n", + "import time\n", + "\n", + "import dragon\n", + "import multiprocessing as mp\n", + "\n", + "# Shim for this tutorial environment; eliminated in future Dragon release\n", + "import dragon.workflows.runtime as runtime\n", + "dragon._patch_multiprocessing()\n", + "dragon_rt = runtime.start_local_runtime(timeout=5)\n", + "runtime.attach(runtime=dragon_rt, auth_token=dragon_rt.auth_token)\n", + "dragon.native.pool.current_process = mp.current_process\n", + "\n", + "mp.set_start_method(\"dragon\")\n", + "\n", + "print(\"Dragon multiprocessing ready.\")" + ] + }, + { + "cell_type": "markdown", + "id": "bfb17bfe", + "metadata": {}, + "source": [ + "`multiprocessing` synchronization and communication objects (for example\n", + "`Queue`, `Event`, `Lock`, `Value`) happily work with `\"dragon\"` set as\n", + "the start method in `multiprocessing` just as they would with any of the\n", + "other start methods in `multiprocessing` (i.e. `\"spawn\"`, `\"fork\"`, or\n", + "`\"forkserver\"`).\n", + "\n", + "When the Dragon runtime is available, a number of opportunities for\n", + "optimization arise which is why there are additional tools available\n", + "in the `dragon` module. After exercising the use of Dragon through\n", + "standard `multiprocessing`, we will begin by introducing the Dragon\n", + "Native `Process` object which exposes further control over the creation\n", + "and placement of processes, noting how it intentionally mirrors the\n", + "familiar multiprocessing API patterns." + ] + }, + { + "cell_type": "markdown", + "id": "03fdc111", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 1 - Parallel map with multiprocessing Pool\n", + "\n", + "**Background:**\n", + "\n", + "`multiprocessing.Pool` is useful when the same function should run over many\n", + "inputs. With Dragon configured as the multiprocessing backend, you can use\n", + "`Pool.map` for data-parallel workloads executing across many nodes and all\n", + "communication will travel over Dragon's HSTA (High Speed Transfer Agent).\n", + "\n", + "Ref: https://docs.python.org/3/library/multiprocessing.html#introduction\n", + "\n", + "Demo pattern:\n", + "\n", + "```python\n", + "def double(x):\n", + " return 2 * x\n", + "\n", + "with mp.Pool(processes=4) as pool:\n", + " out = pool.map(double, [1, 2, 3, 4])\n", + "\n", + "print(out) # [2, 4, 6, 8]\n", + "```\n", + "\n", + "**Your task:**\n", + "\n", + "1. Write a function `transform(x)` that returns `x * x + 1`\n", + "2. Use `mp.Pool(processes=4)`\n", + "3. Call `pool.map(transform, data)` where `data = list(range(12))`\n", + "4. Print the mapped results\n", + "5. Print the sum of the mapped results" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ef13d43c", + "metadata": {}, + "outputs": [], + "source": [ + "# -- Exercise 1 -- your code here -----------------------------------------------\n" + ] + }, + { + "cell_type": "markdown", + "id": "b7fcc5f5", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def transform(x):\n", + " return x * x + 1\n", + "\n", + "data = list(range(12))\n", + "\n", + "with mp.Pool(processes=4) as pool:\n", + " mapped = pool.map(transform, data)\n", + "\n", + "print(mapped)\n", + "print(\"sum:\", sum(mapped))\n", + "```\n", + "\n", + "Expected mapped output:\n", + "```\n", + "[1, 2, 5, 10, 17, 26, 37, 50, 65, 82, 101, 122]\n", + "sum: 518\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "d8e54e8b", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 2 - Launch processes and join, using queues to communicate\n", + "\n", + "**Background:**\n", + "\n", + "A `mp.Process` is started with `start()` and waited on with `join()`. This is the\n", + "first basic building block for parallel programs though in contrast to the\n", + "prior example employing `mp.Pool`, the return values from target\n", + "functions are not collected and returned to the caller. This motivates the\n", + "use of `mp.Queue` for process-safe message passing which, among many other uses,\n", + "feels like an especially natural fit for producer-consumer code patterns.\n", + "\n", + "By setting `multiprocessing`'s start method to `\"dragon\"`, all of these tools\n", + "from the `multiprocessing` module will leverage the Dragon runtime. But Dragon\n", + "also offers tools to unlock opportunities for optimization, tuning, and\n", + "control that `multiprocessing` does not. The first basic example of this is\n", + "the Dragon Native process object, `dragon.native.Process`, which supports the\n", + "standard `mp.Process` API but expands on it as we will see in a later exercise.\n", + "\n", + "Here is the core Dragon Native process pattern:\n", + "\n", + "```python\n", + "def hello_worker(name):\n", + " print(f\"hello from {name}, pid={os.getpid()}\") # stdout is not generally a best practice for collection\n", + "\n", + "p = dragon.native.Process(target=hello_worker, args=(\"dragon\",))\n", + "p.start()\n", + "p.join()\n", + "```\n", + "\n", + "Here is the core pattern for `Queue`:\n", + "\n", + "```python\n", + "q = mp.Queue()\n", + "\n", + "def say_hello(q):\n", + " q.put((\"msg\", \"hello from worker\"))\n", + "\n", + "p = dragon.native.Process(target=say_hello, args=(q,)) # mp.Process works here too\n", + "p.start()\n", + "message = q.get()\n", + "p.join()\n", + "print(message)\n", + "```\n", + "\n", + "\n", + "**Your task:**\n", + "\n", + "1. Write a worker function `square_worker(i, q)` that accepts an `int` i and `Queue` q, constructs a nicely formmated `str` containing the worker id `i`, PID, and `i*i`, and places that string into the queue.\n", + "2. Launch 4 processes using `dragon.native.Process` (though `mp.Process` would also work; try both?)\n", + "3. Start all processes, read and print the 4 messages placed into the queue by the workers, then join all processes\n", + "4. Print `All workers finished` at the end" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "29b212cc", + "metadata": {}, + "outputs": [], + "source": [ + "# -- Exercise 2 -- your code here -----------------------------------------------\n" + ] + }, + { + "cell_type": "markdown", + "id": "f35a5475", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def square_worker(i, q):\n", + " q.put(f\"worker={i} pid={os.getpid()} square={i*i}\")\n", + "\n", + "q = mp.Queue()\n", + "procs = [dragon.native.Process(target=square_worker, args=(i, q)) for i in range(4)]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "for p in procs:\n", + " print(q.get())\n", + "\n", + "for p in procs:\n", + " p.join()\n", + "\n", + "print(\"All workers finished\")\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "1975b9da", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 3 - Phase synchronization with Barrier\n", + "\n", + "**Background:**\n", + "\n", + "A `Barrier` blocks each worker until a fixed number of participants arrive.\n", + "This is useful for staged workflows where all workers must reach the same\n", + "checkpoint before continuing together.\n", + "\n", + "With Dragon, `Barrier` objects work in single-node or multi-node\n", + "execution environments.\n", + "\n", + "Demo pattern:\n", + "\n", + "```python\n", + "barrier = mp.Barrier(2)\n", + "\n", + "def waiter(barrier):\n", + " print(\"before barrier\")\n", + " barrier.wait()\n", + " print(\"after barrier\")\n", + "\n", + "p = dragon.native.Process(target=waiter, args=(barrier,))\n", + "p.start()\n", + "time.sleep(0.5)\n", + "barrier.wait()\n", + "p.join()\n", + "```\n", + "\n", + "**Your task:**\n", + "\n", + "1. Create a `Barrier` named `phase_barrier` with 6 participants (5 workers + parent)\n", + "2. Write worker code that prints `ready`, waits on the barrier, then prints `running`\n", + "3. Launch 5 workers\n", + "4. Sleep for 2 seconds in the parent and then call `phase_barrier.wait()`\n", + "5. Join workers" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "dbf19fcd", + "metadata": {}, + "outputs": [], + "source": [ + "# -- Exercise 3 -- your code here -----------------------------------------------\n" + ] + }, + { + "cell_type": "markdown", + "id": "f8f3674b", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def staged_worker(worker_id, phase_barrier):\n", + " print(f\"worker={worker_id} ready\")\n", + " phase_barrier.wait()\n", + " print(f\"worker={worker_id} running\")\n", + "\n", + "phase_barrier = mp.Barrier(6)\n", + "procs = [dragon.native.Process(target=staged_worker, args=(i, phase_barrier)) for i in range(5)]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "time.sleep(2.0)\n", + "print(\"Parent arriving at barrier\")\n", + "phase_barrier.wait()\n", + "\n", + "for p in procs:\n", + " p.join()\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "90e25403", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 4 - Control CPU affinity with Dragon Policy\n", + "\n", + "**Background:**\n", + "\n", + "Dragon `Policy` lets you control affinity. For CPUs, use `cpu_affinity`.\n", + "For example, `Policy(cpu_affinity=[1])` requests placement targeting CPU 1.\n", + "A `Policy` can be used with `dragon.native.Process` but not with `mp.Process`.\n", + "\n", + "Demo pattern:\n", + "\n", + "```python\n", + "def report_affinity(out_q):\n", + " out_q.put((os.getpid(), os.environ.get(\"CUDA_VISIBLE_DEVICES\", \"unset\")))\n", + "\n", + "q = mp.Queue()\n", + "pol = Policy(cpu_affinity=[0])\n", + "p = dragon.native.Process(target=report_affinity, args=(q,), policy=pol)\n", + "p.start()\n", + "print(q.get())\n", + "p.join()\n", + "```\n", + "\n", + "**Your task:**\n", + "\n", + "1. Create two policies: one for CPU 0 and one for CPU 1\n", + "2. Launch two workers with those explicit policies\n", + "3. Each worker should report `(rank, pid, CUDA_VISIBLE_DEVICES)`\n", + "4. Print both reports\n", + "\n", + "If your system has fewer than 2 CPUs, use CPU fallback and still run both\n", + "workers (the environment report may be the same)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "93054056", + "metadata": {}, + "outputs": [], + "source": [ + "# -- Exercise 4 -- your code here -----------------------------------------------\n", + "def affinity_worker(rank, out_q):\n", + " out_q.put((rank, os.getpid(), os.environ.get(\"CUDA_VISIBLE_DEVICES\", \"unset\")))\n" + ] + }, + { + "cell_type": "markdown", + "id": "aa55840e", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def affinity_worker(rank, out_q):\n", + " out_q.put((rank, os.getpid(), os.environ.get(\"CUDA_VISIBLE_DEVICES\", \"unset\")))\n", + "\n", + "q = mp.Queue()\n", + "num_cpus = mp.cpu_count()\n", + "cpu0 = 0\n", + "cpu1 = 1 if num_cpus > 1 else 0\n", + "\n", + "policies = [dragon.Policy(cpu_affinity=[cpu0]), dragon.Policy(cpu_affinity=[cpu1])]\n", + "procs = [\n", + " dragon.native.Process(target=affinity_worker, args=(0, q), policy=policies[0]),\n", + " dragon.native.Process(target=affinity_worker, args=(1, q), policy=policies[1]),\n", + "]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "for _p in procs:\n", + " print(q.get())\n", + "\n", + "for p in procs:\n", + " p.join()\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "146c2f10-2ec6-4f63-95b9-a75f7447fd0f", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 5 — Create, write, read, and destroy a `DDict`\n", + "\n", + "**Background:**\n", + "\n", + "A `DDict` is Dragon's **distributed in-memory key-value store**. It looks and\n", + "feels like a Python `dict`, but the data lives across **one or more manager\n", + "processes** that can span multiple nodes. The best part is that the organization\n", + "of the data is transparent to the user. When user code interacts with it, the\n", + "code does not need to know the location of any key-value pair stored in it.\n", + "\n", + "\n", + "\n", + "Key characteristics:\n", + "- Standard `dict`-like interface (`d[key] = val`, `d[key]`, `del d[key]`, `len(d)`, ...)\n", + "- Values are transparently serialized with `cloudpickle` or a pickler of your choice\n", + "- Data is shared safely across **multiple processes** without locks\n", + "- Supports **checkpointing**, **persistent keys**, and **filtering** \n", + "- Other functionality not covered here like **broadcast puts** and **batch puts**\n", + "- Data is automatically balanced across all the managers\n", + "\n", + "Instantiating and using an empty `DDict` object is as easy as:\n", + "\n", + "```python\n", + "from dragon import DDict\n", + "\n", + "d = DDict()\n", + "\n", + "d[\"greeting\"] = \"howdy\"\n", + "d[\"meaning\"] = 42\n", + "print(len(d)) # 2\n", + "```\n", + "\n", + "**Your Task:**\n", + "\n", + "1. Create a `DDict`\n", + "2. Store `{\"cat\": 1, \"dog\": 2, \"bird\": 3}`\n", + "3. Print all keys by iterating over `d.keys()`\n", + "4. Check whether `\"dog\"` and `\"fish\"` are in the dictionary\n", + "5. Delete `\"cat\"` and confirm the length dropped to 2\n", + "6. Use `d.get(\"fish\", \"not found\")` and print the result\n", + "7. Destroy the dictionary (to release its allocated memory)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "435a7f82-d8e9-4ba7-8d04-5c72ebcd9bca", + "metadata": {}, + "outputs": [], + "source": [ + "# ── Exercise 5 ── your code here ─────────────────────────────────────────────\n" + ] + }, + { + "cell_type": "markdown", + "id": "fe0ec91f-7c22-4898-88fd-d3a2176903fa", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "d = dragon.DDict()\n", + "\n", + "d[\"cat\"] = 1\n", + "d[\"dog\"] = 2\n", + "d[\"bird\"] = 3\n", + "\n", + "print(\"keys:\", list(d.keys())) # ['cat', 'dog', 'bird'] (order may vary)\n", + "print(\"dog in d:\", \"dog\" in d) # True\n", + "print(\"fish in d:\", \"fish\" in d) # False\n", + "\n", + "del d[\"cat\"]\n", + "print(\"len after delete:\", len(d)) # 2\n", + "\n", + "print(d.get(\"fish\", \"not found\")) # not found\n", + "\n", + "d.destroy()\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "2de80c25-b9bd-4643-b24d-19a3530488fa", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 6 — Sharing a `DDict` across processes\n", + "\n", + "**Background:**\n", + "\n", + "A `DDict` is serializable (`pickle`-able). Passing a `DDict` to a distinct process does not cause an expensive transfer or serialization of any its contents (the keys or values). Instead, that process will share the **same** `DDict`, capable of being accessed or mutated by both child and parent.\n", + "\n", + "When instantiating a `DDict` object, you may specify the number of managers and nodes\n", + "on which the `DDict` will hold its distributed data. A `DDict` automatically starts\n", + "up a specified number of managers and an orchestrator (not shown in the picture) and\n", + "user client code interacts with these processes to transparently provide you with a\n", + "distributed key-value store that can scale to any size and automatically distributes\n", + "your data evenly across all the mangers.\n", + "\n", + "\n", + "```python\n", + "import dragon.native\n", + "\n", + "def worker(d, key, value):\n", + " d[key] = value # writes into the shared DDict\n", + " d[\"hello\"] = \"world\" # keys and values don't have to be passed to child proceses\n", + "\n", + "d = DDict(1, 1, 32 * 1024 * 1024) # DDict(managers_per_node, n_nodes, total_mem_bytes)\n", + "proc = dragon.native.Process(target=worker, args=(d, \"x\", 99)) # or use mp.Process\n", + "proc.start() # starts the process\n", + "proc.join() # waits for the process to exit\n", + "print(d[\"hello\"]) # and then prints world\n", + "d.destroy()\n", + "```\n", + "\n", + "This tells Dragon to instantiate and bring up a `DDict` with `managers_per_node * n_nodes` managers. The `total_mem_bytes` is spread across all the managers. For more information on creating `DDict` objects [see the DDict API](https://dragonhpc.github.io/dragon/doc/_build/html/ref/data/dragon.data.DDict.html#dragon.data.DDict). \n", + "\n", + "- `managers_per_node=1`, `n_nodes=1` → one manager, single node\n", + "- `total_mem_bytes=64*1024*1024` → 64 MB pool\n", + "- Remember to call `d.destroy()` to release resources when finished\n", + "\n", + "\n", + "**Your Task:**\n", + "\n", + "Write a function `count_words(label, text, d)` that splits `text` on spaces and stores\n", + "`d[label] = count` as a count of the words in the supplied text.\n", + "\n", + "Hint: Calling `s.split()` on a `str` object `s` in Python will return a list of all the space \n", + "separated *words* of the string.\n", + "\n", + "Then:\n", + "1. Create a `DDict` (2 managers, 1 node, 64 MB)\n", + "2. Launch **3 processes**, each calling `count_words` with a different song lyric\n", + "3. After all processes finish, print every key-value pair in the dictionary\n", + "4. Destroy the dictionary\n", + "\n", + "Song lyrics and associated labels to use:\n", + "```\n", + "(\"never gonna give you up never gonna let you down\", \"rick\")\n", + "(\"hello is it me you're looking for\", \"lionel\")\n", + "(\"cause I'll be rocking this party eight days a week\", \"beastie\")\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "098b4e60-63d1-4626-89f1-97ca635b9f13", + "metadata": {}, + "outputs": [], + "source": [ + "# ── Exercise 6 ── your code here ─────────────────────────────────────────────\n", + "lyrics_and_labels = [\n", + " (\"never gonna give you up never gonna let you down\", \"rick\"),\n", + " (\"hello is it me you're looking for\", \"lionel\"),\n", + " (\"cause I'll be rocking this party eight days a week\", \"beastie\"),\n", + "]\n" + ] + }, + { + "cell_type": "markdown", + "id": "31d72121-7b06-4a8e-a7a4-dd1c8a6b0b6a", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "lyrics_and_labels = [\n", + " (\"never gonna give you up never gonna let you down\", \"rick\"),\n", + " (\"hello is it me you're looking for\", \"lionel\"),\n", + " (\"cause I'll be rocking this party eight days a week\", \"beastie\"),\n", + "]\n", + "\n", + "def count_words(label, text, d):\n", + " d[label] = len(text.split())\n", + "\n", + "d = dragon.DDict(2, 1, 64 * 1024 * 1024)\n", + "\n", + "procs = [dragon.native.Process(target=count_words, args=(l, t, d)) for t, l in lyrics_and_labels]\n", + "for p in procs:\n", + " p.start()\n", + "for p in procs:\n", + " p.join()\n", + "\n", + "for k, v in d.items():\n", + " print(f\" {k}: {v}\")\n", + "\n", + "d.destroy()\n", + "```\n", + "\n", + "
\n", + "\n", + "**Synchronizing Updates to the Same Key in Parallel** \n", + "\n", + "Because multiple processes may attempt to store an updated value for a key which depends upon the\n", + "existing associated value, care must be taken because whichever process writes last wins. Depending\n", + "upon your code's needs, look at some of the functionality available on the `DDict` that has no\n", + "equivalent on the standard `dict` such as the atomic update `fetch_add` method to add values to\n", + "the existing stored value.\n", + "\n", + "For example, the `fetch_add` will operate atomically to add an integer value to a specified key/value pair. \n", + "\n", + "```python\n", + "def count_words(d, text):\n", + " for word, count in Counter(text.split()).items():\n", + " d.fetch_add(word, count)\n", + "```\n", + "\n", + "Using `fetch_add` to retrieve fetch/added values works in both Python and C++ Dragon APIs.\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "28472c80", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Summary\n", + "\n", + "You used DragonHPC with familiar multiprocessing concepts to launch workers,\n", + "synchronize phases, communicate data, and run data-parallel map operations.\n", + "The same API patterns apply whether you run on one node or many.\n", + "\n", + "| Concept | API |\n", + "|---|---|\n", + "| Start Dragon backend | `mp.set_start_method(\"dragon\")` |\n", + "| Launch process | `mp.Process` and/or `dragon.native.Process(target=..., args=...)` |\n", + "| Wait for completion | `p.join()` |\n", + "| Mutual exclusion | `mp.Lock()` |\n", + "| Shared scalar | `mp.Value(...)` |\n", + "| Message passing | `mp.Queue()` |\n", + "| Phase synchronization | `mp.Barrier(n)` |\n", + "| Pool map | `mp.Pool(...).map(func, data)` |\n", + "| Multi-node placement check | `socket.gethostname()` |\n", + "\n", + "### What next?\n", + "\n", + "Try adapting these exercises to your own application by replacing toy data with\n", + "real workloads and scaling the worker count to your full Dragon allocation." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "168332f4", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "cuPhoton SC26", + "language": "python", + "name": "cuphoton-sc26" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.12" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/distributed/12__dragonhpc_cuphoton__workflow.ipynb b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb similarity index 99% rename from notebooks/distributed/12__dragonhpc_cuphoton__workflow.ipynb rename to notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb index 1ade714..687c2a0 100644 --- a/notebooks/distributed/12__dragonhpc_cuphoton__workflow.ipynb +++ b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb @@ -5,7 +5,10 @@ "id": "sc26-00", "metadata": {}, "source": [ - "# From real sky images to GPU workers: cuPhoton with Dragon\n", + "# SC26 cuPhoton + DragonHPC Tutorial: From real sky images to GPU workers\n", + "\n", + "**Estimated time:** ~35 minutes \n", + "**Format:** Runnable demos as walkthru of major cuPhoton features and Dragon integration.\n", "\n", "A 35-minute walkthrough for the SC26 cuPhoton and Dragon session. We begin with\n", "observational FITS pixels, add controlled changes, and follow the same data through\n", @@ -26,7 +29,7 @@ "\n", "The optional final section adds 5–7 minutes of automatic detection and uncertainty\n", "analysis. Preparation, downloads, native builds, and training happen **before**\n", - "the session; follow [README.md](https://github.com/NVIDIA/cuPhoton/blob/b17cf8a30fa64c466c3e9b62ad98eccbb8f87cab/examples/dragon-imaging-pipeline/README.md). Run cells in order. All computation\n", + "the session and are not described here. Run cells in order. All computation\n", "requires Linux, CUDA 13, and the documented Python 3.12 environment.\n" ] }, @@ -83,7 +86,7 @@ "from IPython.display import display\n", "\n", "# A served output copy may live elsewhere; point it at the source checkout.\n", - "repo_override = os.environ.get(\"CUPHOTON_DEMO_REPO\")\n", + "repo_override = os.environ.get(\"CUPHOTON_DEMO_REPO\", \"/path/to/checkout/repo/cuPhoton\")\n", "search_roots = ([Path(repo_override).expanduser().resolve()] if repo_override\n", " else [Path.cwd(), *Path.cwd().parents])\n", "EXAMPLE = next((\n", @@ -1502,7 +1505,7 @@ "outputs": [], "source": [ "chain = prepared.get(\"transient_chain\")\n", - "RUN_TRANSIENT_CHAIN = os.environ.get(\"CUPHOTON_DEMO_TRANSIENT_CHAIN\", \"0\") == \"1\"\n", + "RUN_TRANSIENT_CHAIN = os.environ.get(\"CUPHOTON_DEMO_TRANSIENT_CHAIN\", \"1\") == \"1\"\n", "if RUN_TRANSIENT_CHAIN and chain is None:\n", " raise RuntimeError(\"Optional chain inputs are missing; rerun prepare.py in a new output directory.\")\n", "if chain is not None:\n", @@ -1592,16 +1595,10 @@ } ], "metadata": { - "accelerator": "GPU", - "colab": { - "gpuType": "T4", - "provenance": [], - "toc_visible": true - }, "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "cuPhoton SC26", "language": "python", - "name": "python3" + "name": "cuphoton-sc26" }, "language_info": { "codemirror_mode": { @@ -1613,8 +1610,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" - } + "version": "3.12.12" + }, + "license": "Apache-2.0" }, "nbformat": 4, "nbformat_minor": 5 diff --git a/notebooks/distributed/images/ddict_overview.png b/notebooks/distributed/images/ddict_overview.png new file mode 100644 index 0000000000000000000000000000000000000000..123b2804003b4e16afd4642300f5892c41a5b6e5 GIT binary patch literal 65569 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�*txjk*e7FmMjrIp?`MtuTb=HnGsn}#k+gs4!6iUQ^#D{ea zqEFI<7gy||4k_Io7)37HnsVe1*F^EbtZ6pa8ziIWB^ms}b5Fd!FBiiqaiYB>lJ40( z=k1U(edrFTg_ZrVo^+#_Ga%O#2^5`7i6vb0*PmMta@B6Xy4K=8?W*5O@4c$KKdDzv z%lG&CJ@+N9+?*nigNO{io^m3ACC$YhC9|Y!akGY>#_u-Uct0tdxoErQOI{(Goy3F5*kT||Kv?F>p;ixC*UET zXB93?0R}mGTN58FvN9B=!ci|}-w2vBg*BnhJHK6tuLoNnz$#Y4!)3ywnTHX%)D`H zR+U0Ee>4;T0;K)KdowliPo81plrcI0B_lxAQf;hAm-(xhzmm}6NSJWQ9{ zwaG+0+-=_Hhw8vXR`tLNPrHY7?7Qogw6*WpKGFjg(h2!J250xmT=IowXT!Qgjx|%4 z&Os1?hZD4Z))$(^Qa2rG{%NgK1;9;|s};`2-58hGxtbKRz2zg3 z;gPiOOf-FuXt?~ElG5w9`;IN44$;4yuYcjJ3_3reXKx7p^kh)XyM43c0?F-KK@aMwz@oo zM+l7jEs2oap8q=4>zk>PQ;(12Z_V#pgE~Mw z|Lda|{gV4wS)*)T0kT2rzJ!*}E`a;{;h)#4k%2!Bh`Kqi5=4exi>@V8He+RD(vW>nf`_d6E-m%gwN61Y}6voSX_y)sO~ff}Yh>Z5j+ z;pNesT}N)|Ou)Vmr8!`?Klzoz`8_(&ODQ^_(x3B${8jGtXO1nx`a3!F7k$`bZM|+x%d3)==6iLMex=piS0BVn3?E{^dQ8Bv7B>Z)ETr zd-|8jy}O$`p876PV5O=xIkNoU77;WBvq{^`Ja>O#&VN=O*g{TU2G#s-rVk-8fLeQ~ zHAn}`^88ExsQ=eOT8c`flU;|`{0AG=Lp2(kBMjVGH@xwS2VjHwM&ftKcPc5H{XO#U z7s9nEs_pMW?rg}4fIr-Oh;mFqrQ<>NA|d2=Jp0#rTfr(-n51D|(%+l(mQcnkzEFb7R2&N1q^GR3l?knZ{dk zPmezQ!+_MjAd@?hzJJ2kfA9Z)_K1KKt3e0fk$6*=ZsN<~rUeLk4y^+&y%sT=N?~Gz zcxBedpWTFZ!Rp-c02u~~KH}oy0M!zCTP*GNuTenizN2nhfM1^f^pz``O1>t&u0{lm z`$CmqS-QM#F$0)Kc8Ywh5x(k`z4Z1EF+T0cURMtO?G}>9e@W!q4=wLU6U3muTxUf) zprZY`-AN+RUsC;#oA|2}-`6m4Nt;f*{a?3ukJn*6R-h5^o=?D3o(9N7gl{M{@a52X zTQS^CDEpaJ1t?cZ1=$&RIg5*n%PhJ`O!cu?S7eY7?oLrvWH9cLQ|0_-Zzai8*KtmI z`YBbWq>G(kPDgPmJ4)~%{n2i8`tR=UGATBActk&Yv$8%N60$;UR6*7>mwub(0R@hH z>Qgpj7xCdBX^!$QG&C@GJIX(j2mN7)f4j1Vm9{fU9sE^x`$rD{>58Hg z(BqLygl`xAO$Ys3=Re1vj|R$ir^Bhq|C-M4wf@I@;o5)?Ddpu$NA_=O>Yp?M?B4%Q z@CC7<;#cG@ zFp4{GZiJ71tlQ-y$)nYuVX0hl?;qJ!WiMAMri#4hON~EpVd!NSroq;z_i{ejoGo({ zYFMJEsbkG>li>UZLkW|^clZM+(;CX-aoF`9jxQ~f>xO4N1hr0zVmi`onUVOJN{)7q zo6fJ!4te8Fr|t{}%#$Q6OYazXTyw3;w1_LAt0TTXN}g=&N`}9!%FdppdeQdzijAIy z$Y1&yJoI8YTw{}_*tYr+$4;Eq#g=)DZNKaw28nSgyC(LW&9h){7jx2OJL>=Y38fNT zy6+~HBe7MwygM_Bw=mb~m>}$|9dF*xptj0^$lq?xU65b(wWQV1#|Rl(C>nDa`h;R( zZSd6~p7tD+ha)09!|*)q^gO)RXu8otc?(laE|v`i-?O$X^pgm^LoJ;dHNsTvKpyH< zj&)(h6QOWXDd408F6!1xjZs-+xz#R}BHYw0yE{9b=AQd`?jlG>WQls(mh#vZazx!9 zs$UOy>`;$gY33Y^Sz%6PkM;2&AfQI-`CK@iVK&D4IqhaaKL@JC@Y48!Y@zr>kao78607!1-Z`DcZ!Do#wA|F~7v06LQOAE=i0lfNd_QI` z9vti&)oCX{hm4ShR3T94y~tG*p~I9P%Tn}4y1i)xIP9jlp~Eh{MXS$2b!6~l829{B z$vY4-s=AGlnV+vY8sj_y^(T5izAqJ${ATj6Fhp^Olt88T&UAUiSTG2zZVTvx&$sU(b9+lqdKN`q*5kj_Ps|qyO^8{ zHnx4=yWBYx`Q>nQtXk-!oHoq^tWAn9*P}WwNAow%c$I~bl;l9W-J@*fM&Dv&YG`w& zzB-gPoX@8pM0h(iI}b({;Mi(`cE^)Wtm*i?CMn!D53@2=IjR+ez0e3cywAuF<<`A1 zHy1MgEgt*%-=XZ~nZ{+kg`U)) zM?xl9pCQGJ+N#>(K2hp5#;Xxk9SkpO_c$1((K5Gtqj<6>O7WBVM5 zilBt-^%|&ePDqb>s8GJOJ)HFzxxhE+{0+O`wldUR3DE|_EJv%~Pct5yfq=-5-^FFQ zu_&@}K^*$EV`qDXT^G;E%8W3p1} z%wkyL6r~7L`fFfYMhyYu+DAIoQREu$mOpGx9&KYMEz89y4Q$E+k=_W-KuB@CR-ix1 zK%QOWG+mbSXO8$LDdxH|78%MKcxf_JYDr+PRIBjqn&m^QAvtN#&sNV4L@6F4JclBe z*VD8?WK0JI!|_fmdRshMbW}FNs}Qz%N4PG^)SfdMR0VNgG7bp7CmtS40OQ+rBtOCh zQTQU9YfGAzLl<-IHpIq*T&fka{QTKw`XVo3jKMb*vOV_RSH${DI5`5^odI~7#)Gn_ z-nVg-^gzXitCcUX@TIS&6cLez6y`%ek@h%8-D4-iX<*WK`n>KP;4}{pzQGm)_o#SjR0vDnJ=HV}TlOFAN(ZjDaYlMfN8Avv|z`+gwaEA4eRcyW3dj zSf|Sc*n`X>xGTauk8OtZrStg&-?O`v{XDpDQ+%#%G|9azAR+U~KJFVJ%BilMxNtm# zPKs2-NBIqHGV-0aOfQ%a{rq1>|E+q#nrimZ#J#z%VN)la>+4yl2|W|GXlO>N#NX5RGT4l4iz16UHnD)5e5XF2p93sce2y9po0NxZ37TkNHdA<3(#+Ag+zpGyo z3zfPOZhIxOi9f{Ouq5;WcGz9YR7?~yX|>nD#2&A)KoIaK;e{sdbhp9z>yvbad8qZIc|T2?LD^H`* zSLxqEa*!o3#{1sjj0Ngc_TW7ek3`!}0$*x8ee@yfdJ6nMC-o`TkzMO~)>&|ofpj!B z`d)Me3JZfOEb&i;Kkq+|nkGWM_%$1cZcC))3&NCM8p|k-k_-S1n3BG8xqtdHCDVBQLz7t#O*=aK#=2!lEY;EV9XIz@)Rd;En({o_4t zLg2R>HZzU>g8KeX;LFd6*~2UlPccT;kE)7)LU#Vgy%r}J2rDoB=D$FZe!TMk+C+Tu zanvh~B9?5JBz?n`o&r0S`U07=0K$AO0r*Jo2|J3uQz;_+;|BiWz%F$ByLY=CT)*xwKx6=QC7pszsgXkVuttI*DW-&aFFpk@E}5%zACm9^&_d1vEdZN4^+Hy+!>X%XAB@`VEvXgS@v>rh3(AP)Kt2# zPBkmq4%>RRD#UT3y41+TBvNX%d9j*^aj7rxVQjs%r+cpB#^8uhycJ-xNOv#}+-d0fJ?pWm@#)_zC~B^L4R*1U;=7Q>-Q%dg)3 z9gejxCN>wK`T}DO+*rVmYN(}3b!)C%DeXF>ndn}eEH*D~;M#Qc>#@8??X1(=Fr9fb ziV!kcW)RSD(bI2#MYP*>;7@|EP{1O9ZAHVIE4e#!v9;S*AR;8Mt3S&^+jy1WL=2qu zr4WHPA$X7T-U!uIgCZ`6dW76@70dI}lFQWZfqG5llee;Z)~*)-5&5koDXi z4=qy-HZOIG->JjQPY~*JoZ7MdR)rxLe%4&X$+u+veQv%>ZF zL9k&65!V;jJsq=#HOFH_38^<<%DAnU##eJshVs2hAaPGT{ex{qy-6_Lj)3J5 zN(gI~LLOwwwVyX3A@iXJ6AF(9_PxsXv#0C8STK1gI9-A1X zL_Ze5Gp_~oEmbuY4MOr=$rXCE%4Y`tbHSCeGxr{~M!t@wO940_2*FyxztIis)jHhg z%$MtbTPP>Taczv7I=Js)CU8*u^07nK+SQXBrRNi-Z{7Y-agu#U2v%(r-OxLcA&y6o?fbABE|-e3~W&wY)br}^L@ ztHF^~F$OU{!MpBq(N9eQ_?41^yGh1t>srmx-a?L!apC@TyHQe0)uJfu#>S>^wgSck zm&u!rY_rG-6HuSh;OK19d@PU(f13Y_XB;JP5VPRRFn$z)u^Fw3>w|)qlV!^hFUtAdE@$n65 z+lK=0l_Ipt}udn$Jg(Y7Hgu$2)aDFzu3jN<_&5&plF*d93LhJBf%?{7#qJP`OUVYd1C`U#R z<~#Vl$EUM_aMo-sZ)3lcfPSr0)iUm}E0${Ckz2~PYey!G`*Dth66s`PNRhe8DV5*$ z*wkc8f~7xNIL8rqVGPv1omv`EfMY2pp9W>=D8qv=I8Fc z^g3Tg3E0x2o7Sa3>6zjbx_WeUorJb1dbHs)J#Hrn zAQG95MTa!EwWo}VhVW+P+r-FQ6bem5_w?gkQRa5Dnz_16_pb~LsiILIw$;iNd9CRx|Hs z7^7iL(WbMkk#Uz4^1NNkAT&jx9&EV!GA74&)qK-oqznjBLaRF=v(x059@nqd2A8Og zf?2VWi>QspT57)bk}i`ZPTmP5W;Lxz3Z@8x7{@P&XW)7EoyoX z__2wsp%=wWFVbQE>XAoTVPPsn3wyqzt=!ZmfOrT8Hg zR4x6llVZwM%~wN%rG&@w8(>ePV;U*z)=L??j`%uoR-WV8ySSaHCrHecYO{|J6V&;k z>pKjhJ*IJMT9reth96F<9hPe!*Jk7XnagjTg3m8}2nWFG3sL)Y0ZZ`gdF~lP`qlbr z+44~Z7SGKYc#=QzLd^kza;iY>WBekhH*2()^Mx>3e;ep=bZR^8GxhJ=G(Oi|0i>1euQhuo zq$|WGHcnhCGb7^{AtLP_=p~Tbg)jeAUNAOOU3Q_DV-1!LOjsq28PiU@eFsP@bOb$?@EGrs}?Hwg-8h6bq-TU{M zwzMr~k*;aSECU0!8OYQtkzxv*YkAS{99rpke9jgg6iLm13W1V(;*lv8YOdt6+0UWF z^RhlRq2weN&6BNs@`@+Vj%p#zk9-Gl(7HVn^k|80kxo@J*A z@bd!}$m^h|?Pj%^{(9{)BK@^Fw*r45L~zc^O<()-)b;J?wVwq9Z~2W&A!lzSMq0!w zn{;HL${!Ixz`o>t@`_A57A#g3mb{52FzPW9A}uvvO}rZo|J6F}Vb+C8>h{3BDn z0ks-~io^2N1XfcA!e)}Q4IfAVabe)tB!!qgf>=gmgZp9n-l&kJ6!-txKEP z%c8PHfuR=Q1F?5^`##)3<>1Vwc2GVFNzM9o&=!x1;gc7wzsBOcbde?=VfnBE2od$$kvg_2!`C>4!xw<7^{qrs_W24|x@ zQYtwBuYZdouX;DC zYsWRQ5=sNH3DPu5rCnz}G2)#$R_E^sbZ-Fp7pVAFMEt20 zcN77SeLhYHXgq3^4?$4T;hT%A2gLk6{UoDdBzCxo1hL}yZ;85Ix=qn+^Uo&mv*-Ya0Rz{_W_6QHs}@0EvjWXq z%ZBiT8dI5_^wHsU6#Mr#in1)Q}^jT}HS^|*sVw}MW{72u#jzLL2mpP$vo4^u>zwr8t`RrahUrR-}C59{- z^Q?3L&^z2KR}}@>2qajZK8*PIR6*5_W}1eP#ZQ6f#a|^u|Mj{%ne1A%N_1rc7=G|+thkFmIK_@(7t!;?P4H{~)xRupz-AQRSrQ&1Y8Is|AM;r5@Bm8;*k}X=XJQzJ9uMA7 z>?wHP_Ewzcrl+7mgr3a|4vI_37WoDVQm}vYHYqXj%JLEyD)^-NZ$w>S5xjRNoxJyb z{-RDQ*UOjf9}EhmLc4s&Oqc(laqfauw?EG7xt7gZB}wlNFN;-VK9cROKlB!Q2d@ec zlCtNU171}tYR=|y^89rm{jvioT?g%5qNz3%m`_`QbIPcoivC zk##HvHw&g%GSRDoZn++c=jE2Xae}} zro&MntMh>8OR13%w)LU&cMiDQk82(*^YSHmxrq|)uVZeP7*`)S-fcOc7eDcJtepf( zzu`suM6zwbdJ>q?Tc}EL`h8Vy@HwQirdXt0YKyeNZ6o`2XUiXg?PZq@PHk{YHFbyg zi!(xYF|X9!zwKj{c>pWzwt9vO)=4A`Qwxa;XLih>9uYtm91VjKIazGJKjSv=?;g9b z)??tI64nh46_v6s7pxtwJlN0Iwvy^vPwO#St~lk?DbNcCCx=MP_UH!ND;S;LoUu~~ z@btR!MM84y&v{|iWpi8pblThH#9!E1I~L5DD*^XlUkVF?9daTkzTjQ6kCFmhiY{E~ z;!V}07_BOnepLYQMVah)*#WqRI$DPR`M*$*uJ%79h4%o*)L5(FfywjO@--h7F*fv< z`rgQ21k2p#DmJ@j3YR8$q%5AmR}|hTX)-%GWiDk0uVdeBHwkM6+>HBckJkmqOcx5b zt?~$v&m~N~N~#l*wJhqNMS7Hhn%E_3zY!F@W41&}HUDwx*RpHn-3H=L){GJ3jlty~ z*QI-AUjtcJY8M5P=WKdTDEWd`;-+Y+ZBXj*Sh;&}B7B{BIslyWBh8T}3$&9ACz1(`_Q&yI)B{S6cX9v-sKFwRL`4I# zA;d@H+yh0_Vlzt8jX-WbV+IBtoG?uT&_1Fi|;(b zsM67Inl7w?@YXZID}NJ9A2}NxzK?+*`yH0%{2m>?!v~E`AnS8!0RVgOEduS>N64K% zy!y|$xpD|7IUD^21()UiAsx2~9Ax`(DY;ceoJ}mc>#`mE#g-&J$=L}QFw|x46e82ol%nBEf9lfvV1ljkmFv&V zg^KKHkg3?uFFM!<>Ur=DRAd*2UaC!YU+6_cKoKNLl470@^U(YjG*FL*wh2A08hYg8 zIXd}%3olukF-kUZ#a?DTB-sE(Zkf-OE0b#KIrdYCric6ttr8-oyF_DG<97VW`_%@y zjX@yxW@cY3v&vPNtoHvJd3MNMAyEwY?deFOwK9-_-=`lh_r>wuh-zd8`Ye+|c2k(& zCeHygRk(PLb?y8~0gCrrT4|nC+q}s;pvVgM}7uXVK zqB?J%oKY@(j7OmfaQk~BdYS69f0c=fKSiQIHZ6pQXL_h$kSKv&XY_2JXzY)-{qc_O zQlj&X!@?)t88@xqLAk>+)T2K0U%rMnpcKqqi^hA@IqV=#Z8zoGVx=Xy_bMeb!^Y)G z9xA0aC;#0Dd+z|fBUp#>3dL;sYEVQ`weq7w09Cu>OPs282Y0Qq50#l!rHKHg+dY-& zlo46(Px-+QRpfVay4Jz=_BTJ9jlC2c>z;Tf+;tmBI=aWD+7n2vtkq%RZ*8pNu6|++ zR+;V5x?MAO@CiOz-P~&_D<&W?)Ioz}pq^o0qvmK>t&z&Sh4N}FYcjB+Ndr>HZYuzp z7*z&z(}O4whv7l2u20kz*?~;{0tJSClk?jzSWuFS2iiTKD0aHRqRH8ybLBx{L)}86 zN%{B-1yx-U=ICR9obeCjqKHUUBORW;QbpqL7t2iBp7AZPI3(LeTx z^2P7C!F~r3NIX~ijA?srg#!q*DT{AAXeS8r7GBm|HP&91zwqK0r4;~n%NKpiH8|VM z|F(dL!jYcaJ4Q~lkDYm8CS{vvMiE>qck=mXJl9VJT+cU!Dz65m2WND|p~SlasnE>} z6J$rM^3P&HtV*&<_e2=hEDc6UneH9OFDxA7=wsv<$KmJ@_XEzMC+(4F>zKsfJf~=G zYWnD!hH9GlWLT^sX)O5J`Z_KM-;5o`Y=m@<<}O0_hr{+-=UpSlu!ZMY^LN35T~)=y z>JQq2nbFjx&6v6Sg;(feLD%iB|aqJ7QJ|6DuWG`9HPL_f6<`iqq6 zVyRoEa}!8?w#OzDjb2mZ+Kh^BHPtRzJzUKCuC{&2k;$T`>M-efA}Dg~HKR+mcK&GK zdKRum?sqrTi`O{hU*k^drr{<=9&c~rl#R=&96hlDS;k*f`lYJ&y2QD2c|hkR$r=np zK~!`ahnaO_ezG|LX99X}rEZ0xbn&rYk|(yyVtZ$mLSKih3}~;T{-|UR;QH(Xe5$YH zlj>JStA=M76J=YT?!&B{ORwUxgk2K$Y6d0${~gc_%JM+@j^*JuS-T4*lL8%4s>xJO zTx;$T;g&uT{u8w~d9uHnGln(hek;>n`m8bKClQFOdrCPNkkeiE@uj~!$P~~NhniO-^&*UST7Z|?3 zairU!d|7X&{di*r=1sJQnYC*Moz~CcX9lLD11oM6kUx18eX@@3diSYq;iD+ULRcxu zC(<>d3{}TZ@toyno_si zb!MO3bf-I?VO0#(2Rc6d`ps(>DdTNat(MOt+D@;KT5rK@l}kZ=0GxFT<5#(|NTMR3~Yg(F6C*U zefFPxA28a)%S@u__nrj(f27p^@5528rJ}t-hdU|^`VR*EUte+3jeJ&^XjFguKYS@5 z!4OleHLR^+Z2CW*DEmK61g|3nCB1XvJFfqDdYQa{>3szTfBt`R4F1<*0jq8)=$O8H z-dOn$mIIjHXY@>>EW0}o(f`@^f#>#rP}Tl{`}Y4>bUO8d#>U|XzF%XPTGOX1pX-yp z-Zd%GbXXZL4VPa|1f#=z2x?(LGQ`+moLvJ`codM;NTn>xj+VLMp*Fd25a==#*asC*Z3xf*3s zU`C%&ZtLu(omq7s9qpANWu4QR3mN!B03 zICS0n00wFA@4$U4rfX8!uT+DnjUZWtohNzZCk)C*r^F(B6oT`AUeo2CUlM ztXJ{>YaRbjmfOR6ytn3lnTlS__6tnCz|eQ>ZO-@WFEJ#E4%I@-ojqj$UAb}mr(MHk zDbX4Bu*Id$0!bQ(t*cj~a;Xs0}UamedUFS_M!1`Tlx4sD=V83a{?fQCzx>Ka%Pl{$CcMoumli`?q=~VCl6p1>iSCB=bSBz7Ri|h z)Uh8ImK(R`=D-8k3zs*oA#%^VrZ64>9VkfM!+diXJ~GH+0krB2Z+4hP_f~mjiLRpjl4%h1I@vAPw z!`f7uUJ8nfECroce`*Yr{8HXZh{c0T~S*i{1H`J}vc3pJUfpQgJ|J`$>0iRqG05wx; zA^-kr0n5(ffx3w|fP5OvDLtuICyf{={q7V*s!=hQf37*mip3{~>{dD3jI>MWzEECv z#$PqUZaH{+sf=HU63ZRZtwQp{tm*70WbV2xZYROKqpe|~beCQ|X_;F=kk^3R z*&UNo?~%sSkRv&hOWDTqT~F8GK_kFc&1v%ZR+M}?uh5R>f^e^dH&00*KU~k1`Pzvy zlKZI#;A6Z6YT_V88Cj`P@q1Xf^vumbT)~$fgnjtkDU|ZOtO*(JQ*T1OO+GS3Dsoxk zcZACt<+pCygNW-%C8Gtrr4&MET7rpt>Kd5K?xBMx)?9j*I*8*#(eBMg7ND3+1{O5hUrf@Lc|;6+@VzECf1`5vuzH?{f_7Cc5~skpY4xC( zyY}qQTxn-FMPT<9-}kGXHuBJX`()@^K->1Oqmn))N7A3+I+$(N9jnS~?Es0*jlxVx zFsS9kZ`TV;cEu}2&=~xzvr&FQE!8T+S-+gDFYBZfaB})yUX%Tfsr2Snb;Z)XtmQ!8 zLB`?*$2}m=?d7i>`kAcBKE>MqDe=XhS1~YfXSe97dxrn3X#9NP;4?ldoSW(z8+OdE zUb_votz0`>jUMh1IFeE#v{X^znn%9_%ZJKBeVGG)hE?uBt7 zhjznEc{ZMhmO$s^Zj9N3estkFPjCkzqkjVP%RY5Kc7CmLmUt0nM$jA$n;;c6|M?!< zCAn;X3|hhvD^8=hOm?Ebujmc^TiP3PxSldnui*&|%{$pp8d-#d$az3R z04(7X{U%wZNl~gaIq+4r3@vPVTz|r%8QayO^u_qnb7@YEMl~tS4?35RZrG9ZPEhqo zcLlCb>~yK4lwouB=V5<0-^|wOf!)25T%D1VS?mrab?2Yymi6eYQiZ^2<>~c+<&q}( z)7?egKCU7IXy*2xMFrt6n@0lhdvvLOSP53knXk=%Vxh9#?!h$*N08BNSG%UHt((ri z<1U;xkD?fQL#LGO6CRL>DNFO4%Chy3@*til82o71N$N-Q2u2zAps~~_*TM|AU&W@@ zaO%cUxpl_aHQEj!SBio^GOe9Ex6zjtXE8K)UJ3*v%))Y%u41-2mG@@BBWnW6JK-mx zq-Ew|W!%th6QP$6M0rz#FB*Gp5U)FxP~^iEzn&c!_&7T+@3LH^+`p|F2IawfahVmJ zBtP&^9eK1LH;?aEUf*2CxNH+(t@nqOD?@e>2E&|W;*YZ4*Nm?7&k7^v%dZkN01g5L z7Jgp_6YUTzrSz?Y(q5Ha7EbW%n#aFYUXNTkRVZp$wB`wY0%>pVtlvWaXEV3)PGL~vCtVI&eRNUI2C#l@VY2x9tMT-d1(iQ(1aIAS~WHoL#{(WA;!f;4c zBs;_Y^jH;{(B#hLOs6-4g(cY4)OK!5xi383*ogJHk#i(#l0uy>>-My?Hxxrp^_(dG zgo~x|@bvxrL`-l^$ll!zwXXK0i1rQpDVJwC4yZlPvCsi>UBkk^1F`e@ol;-r?Ln2@ zcc|8~GBV7N52cl^wKnZs^0Hp zn4TU>#NNoB66dmd4rSPp%iU^LGG@oG2OO+REr+V9W8yvh8-0jpf0{29QQt2K4d;4z zDH>DX6PtE4`%Ir0eu_(3e@!2IA6dTWOw+UDwi--zn&lV%gWLW&P^5WyPY%UMJ=a-aUO5^?wf8rZw!Gz z{*gi+RD%W=BX=HQE;_nza~q@0h57T*P1_YT-0sBAdWZyK4rhJ)0<%!4A^4!7FUJIZ zi4Ibb+B`!$;5dd_L?vlPng9<9rtn7XxM(E@uYM1Dq89Ab*u^YhBMVx1=ht55*b2Td zz&&fLGPAPt#Y1jN$a`_Bby*)q{uBqEdjSB8*+5Ea$!FNFM5E+o?!wR__&5?c*ZrN} z(1jrJhFsnrJjrp$QMH+8(IX>FCtmJh{edGWUPQ^%g8ju${qJxV<`udSl>rw<`p$490AroZ=zQW5v96mXzTX9pA+Gpb~LKU;KK z3o?Eg?knm2l!%>JKc;{45{$DZtH@d^)qlp$@(32g1LGsGA#u<~7(}akRTzfo}@rJ6)j=?S2Go~zafEIkSmvkBn zPp8pRrZBUO85xdlo^8g}j}_q7(^akpBk7NPghi5VemuZK-(MaDbDa>_6^|+@qSNCZ zgEEmH>AmM>UEDpfRi}GNJQ_q&-sqqFE`q;=susHF)G2Ub#VZUI{8+0riGV-i2@QPP zymzRy(y7Yl{IPxW2N8N&(HSgNOYCzQzKKU1y5%Zjm5y8L?3B`DHdj@y$O$}^o<7vu zBgDVjG-DAhhU?^v2LI|XyNowbWt70fO^0o z|2y*<4SH4F{CIH|wl|YyL{v09eGJ*KiD3-^nkVwi{Qv@HYGTt~RzlC$)C~JH-v4D_ z1+rgVHaUWEpE|%mhDTwUT-VsFFeh;Q@WPhP2%i8xxXW#)XRiSd{*{BkhLg)%PQM@(1SOojB{^F&@h z*e_y+PKu zA|X!Tp{a^dg}9y)#nX^oPnG+Ow;Z{Mw-rkgY^djHIK6+S66{v7Tg&2p+^eI<-gPGf zE(yLUJ-vau&r-x)(!p;lb{*5ccUs&GG=^;S)Wb|(PPy>-mwucH_C`OPn!EDPJinhm zHn6;J_G<4Eq|pEKc2vX>#~N79qf`h`u6as9$2QR@&2d;RD(~T$q8yfLRGR{KOHHqAI8vjjrRwc+OW^4vqF6uU$ ze^B2rV8Js|CjG%AY7^46!8Fwo7)=)?6Z*C~GG8Y-VsM}w)^!CM4=0ALsW5kzUr~7` zAn>>!{ICYky*QLDI}4UTVo_e}j={(VPafqCb%dVHHY5-xVUVON(4zLAC?>#PdxxQQiRYWiyQ41Z!6}ia33@tv{L96>1n|j1HC;qNXKKB ziu7M>?edO7(pw*E%py9wFx!eq_k}i;kO02H#9nhqbECS?hw{~})HAM!h93G#OoDeW z8edPY4A7wG<1ggC+Ugv;G%@ABL*Jz7vQ1y={ZksLkbR8@LplK{dD*P}njYu?-j*@?Rz7CF}25dyjBKz-5!EDp6jIvs=0`1y}DXJur%!Sub90yRZk=_Gzn}*RQ$kIgjGC`d(Uk@4u(w~5_EWS2F!ECht~S}KxG^bdU@`PSrZ?`SNkL=TsG0N9Zh|NSo zS=p57Xy+;k)yoO#Bbe5*nTvP|0uBGcqS8hzIK9RHZO?fydb?LkRWOufu zn&9B*N+wlMXv51jL8>s#g|8z27@HL85w~4kO`2NMfFnHI|O(zXO?L-S4*+2>kT>?>15F#%u+Q&!Xy-e(`DPq!bKu#_8L&kNe3#qzqDm1Lt+yhkNoh&*4Lj;-Fcq)SbY`Z9q=AbHR2i0){xhgLi zvoes@TaHB;{nN;8T9bAd&6L67Np?eAuC=1y_Sb-99_&>Yg6=<_A)Pmf(B6WZwquP5l`h&x`fIXPhZ`bJ%?T_I>NpH2OAWUg37QnSq zw`zJX&#|SM@LgF7rs?yo((B|tNmcPfJ+cFECv;&v0`0A3X8bp4GMX5_TUGo&)A0=MQJnQiuorVseiX^ua=R!QQgsC-mm0CgpBcp z3qTGVZ=#A1Wc22tJp5I$Y(aa&Sg|U$SU8LeAp+thj+D8=589o-p3XsZf*Qcfbx*=L zH_N+TmozWSWPehlWZ=wlRYY#ygag;#lr*Ox#q^h7L;VD;x1JNG9a+ig$%8o@RnmYk zV>AP7KH|NlbK{70jz>Xib?zzNOgba2{=^6vKKSC1*k_12czC-VstC4<;mu~WTauOe zMB-TvY1tR*HkPlij~4Qs5Zm^7YnD#boS*)bk=gZ=LoQms@#xla#r8417rDmfRwG7+xD>1=3L zP?krS@v$7LwC?H=&GDgmGry}%N0C7$6W6KyN1|idLrj=x%YjN&ty6NkV)MLGy~poR zSp4r(*V0y_2|eo$3D2ZlZ^FB>K;Qr<&`v(1o9pu3NU(vKc$U6LDj5IkRn}yIj8&Ag z+spCiI912t1yXPn;fG9iWdk)2)*wrlcuP(ZZ1Dcy)O7C3=>CcOX*>JCaX&hHUK@1N zs-z5SFMC#sbQlk!z4yD}27xM8856(_T!5tuxFH}A2o{$y2^XB$Z5B?vm+c=EBfbd? zVmpsg@=S*07_wR&x8EcB8~ZdExAX>>-CGOmU^l1fKh@WINJ4g@j9xyt+Mb7OJSX<9 z2kt?|{(ujyDwr6{T9zMN4N#H#Z!G}neef8@r$JrX+kEUnFqv&sxris+z0D-^5j2})j=vERri z)kk9iKBZ{;#0bl2$AdcnMfy&GvVo6kIoHdTtB-9RX(m4}8ch^T_KT|gNrv(M z1FDc!!+T(!;a{STRXnfVHhjEuj2f~Wm@|M&!h`J|cWlc@cE@=&svYRT|)5wYBGQ5kIK}FTt3WyGUdhIrb#q?z7fM&l2t*o+)Y2iAWdyc4^&9>0iirs3#DNego z1|&%09%Y6%&Bp1+{6tuo@O={o+-#ks#CK$MIeunqJ=s!a@3?C;;ISF#>jseOSY1>S zG!JrORT4yey$Uh1`Sk2@M(1uiU7YgSc=V_n7aj!4bZQa;4%3PHNA#Vhz}OFH=vsHs zFMJt;CxCXTSXeFo2QJ1mIe#;qP7Mp+vpGYbStLcAmn9z))xC2oB1xQ}aX92#D?~B# znrgvIO3hQGDHTJR;O3+31+(-XvHdXkfm%9Q5cLDg2$>wPmjB_Ba)6K0vQk>NVaWZ4 z5lC)LBX(b2BG24j@7h@kmb_CjQXy>km|)|5NqF&kjcuh3+&spM2P1o`6dZbHb?I!U zZOGZ#8RHPMT;^gFLF&0|2irNQCOQwdncx2hXjSt*zqn}cp;{h~eC#Z0!oERYJX^^T z$Fk_Z?7JkgzR#Q|BcY-&F>toS$g=NxBfbUxvM1wDv(CmbrqQiUz?{0!lHZ&+O+{4- z(VT`AVUn?S2VJ_|V0LJ`{=q*8kDRP&F~EMPTB)xlt3hOjy_?9=#r z4r;bsX<aCdIUZdw3r^Wxxl->J?IjI$x}~9Z zFq?PuiS1*N>{*tqh^u0*`xp12P|Zt5rN~6T*^eg<8SN%PqfSFD`D0SS&VaHajh`WW}Z4s0*68^3dc?e)3&eAjC9iO6HB;(A> zH4>VWnm=JX11scmHpognVH?YG;hSOvw)L}GvCrDGzb9AnUMNq>Bxh}n!Ig$+S=zhp zio$ZUA%t=F9cf;(Dc{ZmIQC{Hbk{V7F43U)Y~{DyMp1Ff1<|wmSO@c{L0c~`?YEs&83v6jW6GJo+HP55j^nlKLAsOY@fYf8(l`|Xuv>{7tQ z&S-m^Yu75`k}j;_hQ`fzSwP;V)jg72c@^TUg`=TwWmE}jgsx7&GLxE6YYDR)R9j=s zCL(Se|KNW)RUX}5wm>me*gpQZ-AMRvkbt4Tv7_GIMGZN8Sxx{^Y*NftVzpXaN`); zHToUfU&$GFwiq~T)%HwJyuAM&lOSzW4z7=KUy(4*1g zGqV_ijg@@*hx-X(HsPuHlU~yldqJVgi=5o@BDWL}{eHo1lI*8Gp||uxfDEIR&CmlR zSJE8e+4!`)tSJL|S_n_k`;1NshHVui^w*AooIe@YqLKaTosdm)>1xt~CS$HcQ^|iN zIPp5X@6k<|?>_B^Vk-t4(0G?dci-#t2IUY5$qBnsWmfeyt5Fju9bZlwEcy$kMM9Bh zD{MFe&z)m>LA?>Y4~Q!k3oxP8>NHQbdt#AB8IO1(HlMFCw-Q4E-do$q;cxz4PILy4 ze94RCf>}21vq|0KXPLKaTSl&=yCLYP-n2P8CF%w=bQwgHiwEbM5%Y+|X1Im558gf~ zq3u+cvzw#pI65ZX9XsbAlz_DVrJ}hS(RL)x*mky>#N&YA^J~}bthTE7CYWn%wg$8< z<-t~icVu1?q>DR)KsGZj;mH>$P*k^Q?w=eKFd!>D)%EE&G7X9po#0#|RCMkF{*Xi! zTOW0r_&VdZJ|AbP=2qw50{$c8#NYsX^JBC=#O9YCK^)xc>Dy|U90xpILaIrRI^D~F1Pa~jLOB%Q z8CWKx`!7W-&Yn2{XsEw!)P9cDT3ds?S8+Kbn zW3xAoM#%~5MNU3RcopfO^rhOTlyAyZJ?D-^^c7{Wt7ggYqe0%&-w*9if~}rgv42?D zTKEB1nF@anp~kQ)`l?3HKJjqD6#Apv_}2k4fW>E%Mz)*?-JWjruBmohB@c+FBUZJJ z{?S$6cYS%WINg__!sG%H&mFPKZ><2gA~@fC>+6+{G|Zo)&Yx>q0tzxAM|E*7-Q2dq zR1eBJXQplI25C7>w_Pkkk6|f^r_|D)d9Bm5%-D~MKo&D$A|Ugbs^%AX*Ea_~MP7c4 z%g1SW1UC)-Fw;sE@ZW2lk!qD(f$9a1sUB;)=>mnyE}}gHU-L4L*vl?rx!E^>^2P)> zu0RSfpkaWLx~j*Ee7j|8{I^(P7RVp{Lo8ZzD0yYZwNipW+??PzDxCb{Zo5K$wbd~I z0Z24a(o~W&c2cbBA?C^9x-m>AW2$ANH7db2ntb3Opk<{{bout|iVW~%t@D*ey9(rf z)#rJ(Ak?p!y#0JzW=>WnxC5DynVG$TA@|y>Z9`IIK?<@syLNh=dg(>&w!hALR({Fn z$YS>yL4I1c!s{tq{uj;DKe!>+^Vp~@vzqF*24beSNr*k#SDp( z2(Ma38-e*@W^(6_6n>@h%pA;0TeQE5&d-@B#dx$Kg>G2Pxqn}Rgji=pJ&7f|L^6vO zqkZ6Kpdz720J~b%ttsj$BsV~o??gyy@o0(V+&TcD_Tc6jx^rUS`zX1s`gbvDt_+PmmWmpSY(Bs-l3J>u`Oavzo12J$RW+rB@4}EB?qM-H@o;>M5Nx?t zUz42=^0A};0SKiN>>(B0sY}ww9}k*tQCkYrZ!v6iIwTVopH20+q}g}+6=i#sasfA8 ztGu;w2E)gLuR=>-y%AT!u=}S&p(RtvBWNXey#|M^&<5Y7CkL$zOCLeACmZyA-xuwL zc_K)dE3WI2i=fOVHQ6r>8Yt>fe-)~0Be`|M9Y=>Pc9}EHP!56gPO*&8S_X>j>j3Ix z@@|(V>Iz-zyK!oI*2hnJxx&kw;I(Bh30Ef$S{gW`M;fNqpNdRYH>TguNgY<-{_hU_INf73o z-u)UN^9T;rp<)t5-v_?&ivOpwAc9=MxUg4MWSmBK=7VS><81n34Z6s9!7-yW1X}?Sn#WU{E*iSI~@{0=!t&=a&WV z8(O(6;B=!hlur4Tq4|PC2%3z?K$geO3m7Pt8aW2F=wb$$2|RS4W|TaHo%SCwS8P5IZ(X}k zBpSd%`ARgkH9SU5S!er=DlJv|yKymZj#&pC?ae&6@pTUt4JYk?`3u{VjIXybvM=Dz z;2H1ka+Wl4F_c{s7IyUd)}UxmMz%CqK5E7LeTI5w0?oc2W?wDc3K#F($~7lrPl6Ug zBUeSi&cl;SWD$UV7pIZs(Euh_uWVL=FyF|sA%*q1zTm;R1>nsUOD>)-^J8;fW^~}H zDQ#L{|94Yb%)R%-u(UWF5=y5Q=v%7pyTgob0gOO1TLu)@iqMx|UHWQ&@bft(o%5v} z@U7H~KrI-Q0J~*kWP_}LI54W5O^xY8j~n7}#HaJz^=6YwU6AsoyLkKI+KV|k=Aw2J zU;SEa5z;Ttd+*^<+cJX!*Cd3>&h8Iz9d18yv(9#km&~*c!4|qaPFFS}icK_rfh+q2 z7t#DQV|C_8GCNFFws!ZCvR>GmOVdX*_KzJE;J0Zsb0`HT8TYrSi$O;6AH?L-V2qUy?FgzTL3w26Ptgp`)sLMqx}(kEq6%bbWz@AbdTU?qelAe>^sMy_Jm^;5O|?AuosEup-3#BR-TL? zQfoBq}CQ8Lnv5I%ntq&o8)P(O>z&Qse-ZK0wtgFoU`a*UL#S8Y&loT02T(JBH z;3hjWDwV*qACLq#ZtX<%4X`mv<>YydlryZ)ki*drUQfifu_K>v#2@%6a{d9duW4UL zDmoymbnDBSru0B)Zn>G|Ep8RSD7e~WqzH2p5_BJ@FTJ7HQhA;XfA&`D6~NsMbvcS> z7!~Y|;~A6X=_Ey;5Z-I$W_F4Cm*vT!fMZ#IE*GQDBMGTg{k#R{KawpG%2<3fzD4l4 zp`cPn(%AW>TNx`-*Zd0%xRAt1Lctu5DSYf2Shs_QfpmLEtxoZkB|h#PEuR1CvIv@~ zPJ8eEt3*rS2UpY1vW4)_7B}1wX8L6mXE9wrtInQs)KaUF`vz7AzR(bKq}kv`@(>vM z4z$>CZ)p;De~UE$yuTQc0^VGKANgE(N=We6E=`rXco=_53!~CgC4j8)!M}PQwW;j8 zaw-NZV_@-^?8qzYA{I7rw`q#x^y;XXWh8hbRn~<$c0jy)4QbZ%8vz75)C2;ssf33Rh z%Z<_GX0pJ<0p92RV0}2y;52ON=EGT~MmVrC_?DL|$*;sKB}RN=rD78@bUt*yG(1UF zF(Rp`SBM-0kZWTE7pqdrq=C~!s2P_HDqw5k)_UmH&E={Tq*@c+gHuK@5S^o^8I{{6 zU=f0j)5es;ygN6oM2~_WUX+hTsSdH~AhOMdW)(rj^>*bWrZY+SMLWr!b;o?JE%>^p`F2@5JU*ZP}O*T^=0wwIEDGowcTorx@jv|L>m3|rYB z?p%RNylJt&2b+|c9ZBsv^t){o_ePG1Hc_?huX#bmAGP(3J@Noi(TLgB{`kVk&J71W zZ7cnLP6Jovj|xDY2NSX>?cnECm+EnRQX=T{J#8$onoHVFvtl~n+ll@ zxTUqU?4mPnN+}$w`V;cF059zq+|t>Wb8ie>n#C@0ZX>4>hj$4ju`32gMX^#jB(;ln zfJaf~eNVB?IICI|&Z_hogQy69vShkl82deKqxKs$V=I3e(US+=t_e}aU}6Cj!*GEj zG`YB&g}7Se^!u2@vf$ZBzogF(No-Y+ZO+S~i5o1B%0vT5S0*M9Lx?cC@OU=LoT`<2 zdrCdfS=4eXUUg75`CTi8gs-0D(W1AM=U>)6WiXqDPJC|*An(t%3;hl z{~R?5i}ET(j6U-4wBWb%*y1fknD?Q0yh#}+NnBh-ULF(ik`LXS-fBiY5((Vh?9k21 zX&PMFsJPaY?QVyQRsBI#zi3xcH8^KVE8_@RyXqHKm5@1B#`MJa!+JLvduxTfIR|L* z`~xW`y%PlG=5kq?TI=I_Vqp2LKuInPc14ghZ+>~-iuv^wx!yd=wC{(DU0R) zfyV*B(Sypde&DWQ?D(D8p$?pqq59t^E%;}+YPo)T&Q;oqr$yF}|)Gv?DO;?lzc{toVZ)Z0s_{aVO{9T^sRw%hmv>)S^C7v#BWP zwad<&8VU<=oO5#XPI^Buw^3JlO!u+A^n$gnevY~qt*|h24DIOt!C<3XIgJ>=ik*l_ zzBsciYf4!r+Lfxeqi7h|zG*+K&XD#CX$3K(pZz0XR!#AGTGn{~w(p<$v0S|@{J>a` zyoWUfr;6n>eUGId0IX#ql+7wACYB)2s_v4)0`^gJuX&$M$9I~&=Y59?13z*+nCWhV zX>L$wFNhJI7#ARp-j9snZ)UEVSLVHqgq7Of4=yP~6=b?EwM7}FJ`vYx>thTff6p9o zZXR>!oboA*U`d)onEC@Zr5ezr5A9rg?KlCs_PTs z7K?iDLa45z;z)`jwf0n5=iYeMx&~n-lknr?@5VBWX9SIXWEgh3=Gxeqaf`^b7&&kr zH7a$F>T_`O6tvZ(bSu0RRn~{?I<-AG_?R)e<*Cr(IJVenC`7m4@x}G(vh(777gFZ_ z^XXp|Dl!1_LrEo>cKvS8Lk(Lo<~|9)#(UFZ6y^>e0^s#;*8WExI{}Bl9P1YU5BAf`-#Ka(X^AJn5hO#+iM2nV`?lhm9;zA(h^32z@LFUi&=cDxizLeU(U<(OJx_ zo(nan?mF1``G8KIfjXK)kO-8969fsOqgq+e&_-79=<;z<`T`s6nDc$j6BX3;T?kJ0 zSb{?a4zEtJiKP!TL3NEfqIyhxWVJ%m7iVP)b+if)1+nv^YE4w>=dKz~9$@0EIhiQH zrzQ__g6z_Uq5%*#%%Flt%M8v2d@E_XcR(o+xa`ALIJSRuf8j!2Ck?poe1cWdJLG*b z05vE8yi$tz%8p7wNmOV5V)ZvL`U5DZXo#gSKi8m`&1ZGfRP{I{@?wG6ku##8wl7`# z38=p|0{y*4%fqI;Ki={6vh_Ta`*>H|(xtSo`9@(&amu^P-! z*Iqb0#Y&k6G-G+t&cI$&W8y8w_@#;RJ+q|~1FM`>Y|s}>rbm^pJU0ZIY4SOs(sh|6 z@N=kF>VxV}M%jipsMqLVnB?rVbk>5*{sWA~YNj6CPSZcmI6>j#Dmh(&;w#Q8Dw6SC zDBovM?ZXZjM{pB6NJCgw&94lE3|zQfIutwo3uB;9Nf*F4D-%0|qV#us{`ix`0vck{ zZ7hI26C|c%(3k%ph?>|LlnW}RNm8ENL&22;mg+RO@D1Sm1$YbT)V+lez&wD`KmT|U z;oiho{|?Kae*NSB|8PZj2~_64?|!2F`z8N*6O*)80L@CIpg0?Q3w$AonCZUPr(W_1 z(C9@v^9kO8LenEinRt)eMFuU9_VHP9eyI6BUiSl7x?BiO{-aznlwS{}`;1B#9gHY) z|BvUeUO}b8FBtIwPt%4s4U9(o+3o=q0uLuAHWptZQw-r^*5a0K=^(-?1eWf+n-dt& z_xnC5ssk*Z;-wkz4Qp}I&b*mTaQ3%TY@e*Ov^*LK3;=LwLCns`=pIOE>nWu=iyX+r zyk#fG3atq-^)uy`uxlt*3DZj;(kZ-?yU!%y(ds=4VeEIweEQ4*|hKmjZ7N z9>_@`6n;SAQ$`oWfOag^ZfqYKqt#3EulS!ufj*!U1*(G&NKcNP!4#}#s{ z)5gOyRcRjLT3Kd0N5^PAF3o=a*@)~FH z41Oz*A)PF9544yK>@gjW1of0Go?)L;ybHdL*Vu6575C-A*BaM?u+i4*ZzX()b4%M< zYh}jWhCd4gqjv~t$6Y@|WBw|R@PnWUpa zUYwXi<2Nx5^T`6uGdmO?nfuOYJd^=jT;FiD%e;>!W0zcaJn+-dAf-flEwx%qjP`g% zT_u7}6~TCji@$=UUsG^Z7wNTs$J)XU*)Q)};{K z_jg3G$feN&o#8XbhI9nZx?Q=8Kh-9WqI`C`eeA!h|p z5ucECntF>FqED{qB8MI330dL2hk@c$P-&tPCDhN_7Ce)A>sq|K1puM*I(_six)&5H zZH<$r`wiygr79{bT5dP;OD_!_ux8bv2e11xd~V{AW?xyjp(q2Gh6 zH1w(>_v3J%5jxP@xu>@wycV8DxpEcsB{KJtb05x3ND{UXdJ}@+3J}Fh1P}n0sN=k;-vYTJ?R$8uY?#Fn>*BQEgMQ*o z?8Q^*L|wb;d(0we$>#>na{x{HLKnKWH^b>F;X<=1^U1{!!>q@HcoX;D9?=6uD4~DE zqpP>sRCmyMnxxSrBHup;sVqPMMW%znH=YS&QSiIyw;19Pm&Z45YClc6yHg!UCFfjJ zn!BH?Dz~jmX66Yc^{SFIcy6fb>+!w-^ z;JZhM1u@GZJ1m)d!EyggR|&$Qhv2+X&D+bPp?&}CUJWN%zXS;UkQ7_ChnXy1Surb7 zuoMoSjY(wkC*8^m9)#(T894ejTRdXTm-e)-**5VUx%4{vF473tK%=_KU=vPwW5+w9 z2kKC-PzCYh&`U~g0iVS3?OG7}^?KML9gnr|gJ#}r?4sA#a-G6&pyS=Mo?-`m@$rFt z`D!ob%v7`$F!0#b%R1QHHW+&yZhBo%@yojaslBKuIn)|#6xH77fUVk)CifKsYqL#& zS@CHr%1 zXcGF>k$u&Q7-PN@8y%Vk(w*b4YfeP8O)&6615FH5~slMzPuFeecDycs0VP zjdk*n%>|hJw|G6eGt>KzM8NqqxIT+d$XrygDOvVC(4svkF?N$>=((GiNWW%KRCiD@ zAIyAIk#8LQmJl`tm^Yt7tmlI9# zzXS4*{=CM*kIpbIy|nq-?nTt}$`jG`_Ye9r)Md3Lj zp!WBR*bJgd(z0Oh8v(lN{LCGLqYpUb=>v0{?%dQm`S5TyTEB7nAYw17rxa1=srmUu zT?%K7uF`)5T5=WZGkt;@p?OE&)8VTGUv&80b8C1`96t%J28kIRdI@8Elvf5p1q<$C z>v)vC*pk9vHqV~?NZvM1h0-Q)OffuO3)Vu2pN+0atqcxf`mpsi5yzM8ohpXXv>gQcm;Uy?|;I2jXh*mmvy?tqvpshdQ8fdFQn3L_jHgUS=J2GaB zdE%W>nQ5GAoyleYu2(0$tS|zt+C({r4t;FjCX=Qj>6_@DOeQO;FL-wsyx?UlabEKCrW!N9;fJ!oUgqDENoxVd(Y}#Ioex~axN0X=z>Vl_@^J!^ElGQ zkZeP*yx^t5L5f%sk#Ah76N$mJCwO z$?lg}_$|QBtVT2RiZ>bO&|L#+&p_UjjWVJDZ#ve5`?;e^ zn$lwo6V7_)xm!vwFqdGaNeAczd4B%A4Si;69 z69kA^UPH0a$L!Tq>_&AkdV4*Hz5OJ~{u}|(tpFJ|jQMbWR-?vkF+n+-<+Iy90l@$~249aVau^qeEh`TS5*>68ZxOWWj2DAbZ*sM`mM`(4t%ugzH>CaL(A(KZ zpeEu+Z2jjL?LWh--~Ziaiq}i9gg>9nyLcIOAj9u}{O>CpdJsBVMGJlp3H}mP{tS@* z<2NS?up74#?uql?Zuk{4{eCit8ia{9Gi{)x_FqPpP354d)u|d?`Cr}-k|1Ls)Ci$A z4g`ew4*>oeE&q!ACcvnQ76e25zq}v3clJJ@%9sEgm4N+skZp4S^iFW1k^Rg2L2$$m zxNz=kMB=|kuLD5uwmWv(zg;;v^y(@Q?WaPiSYg0eUNRAuRv$e&9e`p#vHQa03PUFIk>$1BG7XMa6%4KX~u|6_Ni} zA`<^anY({rjLT5oilFh~9roOQW&S9+sAXR2&=5e z^bQpFoAah{3Ne1WjQ)$PSk+MVrLtS8oMp~M_*3Fht8urbmKJ0r4bN^~P9Q?(vmEJ* zw@)Nc7~FtAZoDHv+wpxU=65clLqJxHs!A>Dr*k+mA0~b+85Y;L`BqU?)!qb|jj64c z(a=$wNmum8X)jnIH3M=P?aQVLaua2yN6lX8j|o@{>{bTMQdEQ0qIQ!xg?v{p|32Xz ztElEUPE4!xG*yA4#H~Bd=lHIT^3nTJ_yW0Qs#~Bx?)*)#MQg5{>YOFVus2HHCTM-_ z4;dOJOVcT+HKJzQnK?Py@!NNiMC`9&D(8%Uc}5#E?qR-4^9uz`q+a>&oxdvQlomH3 z)-&wJ@)+E@eYW35?)+9pHgt-Ws`Wi){psy&+la*%$r+3lH(3A3KK-907n+6|_p>*b zxcvu!|A(vVD2+I+n)#=bmVcA@ALai4x8G2Ff0&;68oG&5oEZTt&OB=VWKx;6^ITWo z>=meakfti+&ls?>Gt)_Jk0**nQ|SmjXK9n2Bq+~?dpK$!*u_DyQ+=W1H?>eS@#cuH zx=6OC-|IoMn{f|W$CjI|A)Ir(8|p~T_DmJbt^~A@h=T@;3riq45>nLhg=+`>-rd4rO zFY7*`>d!E8K3LW>3HC!wVi?DXqIpD}4EVy^9F#V=WX$lM5j-${ygxR~{YwhJlPD<7 zlbS9`%wjJzEsZd$>it~|bwaOMjIq;;_|9&dTP|%W_s_?mQUC0sV_Zh)V&9Bp4_lR8w>q*&Dq%qaiZ@KX77%Fl`HeJ2ZU*%b9d10 zhD=|4cAh`xTtXFZJFzc*f;LCC2PE1u7X8|&fyzuN#n*_9ls0Zy!1w@1FL79^U%mdH zox1om43^!{p;~3h%lB#RAD%t`HVbF@w!sO`)J%}qea-T1U%yxFeQ#@R?RUclL1ogR zoOu0j*uS|qQyEI?M?0V7iTDS~H85h$-i7K`>?YP+6^%b#aN~?%FuxFF%EWkFEAU`1 zPS^JSSK`l?{8w(X6Dhj5eldBPU16d5txJ?s?%6F+h2C6^{}-}3qE&yZ!-hs+!GMxH8KH^oq!Bt%R&z`DPgzD3a?l^t>V@sg<4?K}Q;Owk!F z5v1>HiZT1Fx`=c?<1CHb7p5?DG=C^mtK~SaxZr1BXy-@>CIPVKW^wyNJ5F>k0zvua zAHvyiE#51e-6E)K!ajZ_G+bMYEw$b08W9T`|Fgx~MsY4~a>@&pFPE1es-wX6lEne` zUrKI2R0Yj2`*0LP+lekl#n3(wYJ@(W=mAstdCo_xd|cx{A#5bjWN zf)JK6AfO;^evBUfse?$2Ug!(Q?<17ID_hi`2f8&h%61FvyP-)r%~yz;vOP!DKFS^q zo+0ij4eWQVUJ0uFv1>vE^;$;DBvH8&{~j6~${EqxNvD{05f6q+b-PWK4cZ4X?f47H zF!|8OuL!13URyXmUO3~3=AM;B?ae8@r8UbIt}K2iB8=jGS*KncgHGAZGW&m0D%I8#N5Em%xJchMx4*{cj>~)7< z+r?Htn#kA-`VKpdWc6+1z%{+JrflKVzntqlOrog!`akpE#v+R9H&9exGV|Tk+Pmim1=|J!>HeMyP}IjBroNuHOnspSwaibsLa)eFF&Gp{ zPlsmb9pm;)&RgJU;jd~miTN97-pai^9NzoI0HkV|z8O(o(_?x|;U)1MtFu}_r9=nA zYwlv~-jku9voQ#yokFB(kc<*U~l&W>z#Yw7nYA2-B#=~?9l=_{#bY3l*w8TWmRiFgXv|Y2U3Q5(tgeFrRP;os1sAFI-e}~W{_ExrT^QhzI=#Wi zcPidO4^h-Jn3I{x5C9vwDDy{$0nqmd`ZRbI_p@%{gYif=^FU812S%WP1y=97xr-ta zjgO)-&&dl_-$HKzsqI(iZbze)5-IN$UXzY5!e1d^9;? zb#vZJlRb0>N`Ka1OxMtkrQa+*frH`6KbQcD27(0T8VY{@)D-5MJasW37V}}RY4YFH z(lzv2?k{-i$RaBTwlPi7#$A@q>{71DM1o}Q4=}&eEglPlsy|2dg>gGGJ(yUq%sN~y zuJn#ni4b0EE3v4ghQb+<2rW|KcwP$n!tI`qLF@j_0kJ3_?^+ z;n%NVrvNxw2r{^Q%bRF%JVWAkG$tch{1%4u z!K&VJDDtuggV?9nP){W64B4(!Z(JpG(juGEt6WZmN40lSU8fWQM|M;>1>E zo$^8L9-ylp*s3SZT)A!e3;aLh^yhD2N}%Szi2={KKS%h#(2{ie3sHZd?7v)HX960? zTQT#$A^%Sb?dM{DqW=GW<2N_{7t{i-|NjdR4&uNBQj!`7fC)h}# z)e|9m6aANjONPq>St_QLP5kQ>2X@@>fsaika#HP7DTaRcQ$mr$pIltHpAFK;22gE1 zC0EPVGIl0Bj48+w*Wnq_dbXY>jhI6@fbl`-#UWu4GG`}oX{pMo@^ZcDhEEra2T#Y_ z5AO7rODmJ4qHYANM12idaY7iQf@>^qXaqjF zbfMgOf5CG>#4fV!oiBcX`d)*d+Kq~8QOR8{iWrYqByE>0eOqoML9d2d$H{S4Bf){qOkO^f+JcGa*wqu%iNsX#u2u_sPXkpY8+x{ zHE%L>KA@ypx~XYA+`Yt7iL1t>xu<_V%%jqPfYL1{Vqd~ZG03A4d2G++Oqp%7`mX+j zHo4+tdqwv{f{U)v71!OEkb_#(DX-9Mka|{*aHZ?zm=z= zLYlO+4jXhIXURG}9crHMN`yTdna|J93Kat-;E|SnkiV3~`%InmOQs zRX8Re?LDNg2o{@(77pl1xS>Rf$MfVd3_dZ8`GIhV~4p zT3LY6%-8mA`=umNKK@8RBoy7^bc}Z44(QJj2IX)JsP0L5W2_u zbhR(^A9B}pWGF?ER90%mY|05XAEZYOVXSXF6`<1u3B{nxruLZJLng*r)(`#>qc@`MO%r1`u%42q)r~~ zPOJ0f!d~+9mYzLIo$eN=h6R^O=cXDb_VP^@D{ITwW<^{b#1}w2H64+y*C}7oUbU52 zeYE{Pjl9YRP}1;`W&|Y$TJobnaigSOg2{t#njQ0mBHMwbGhuI*3OW%;WQUNpP)WY! zq54C@#7_*36^Nos;`(Km4u*Mhp35j{vve($R3C+^e}3jux>E&CvFCJ~Uz_o)&n~db znW{V;Y)_3cQF`Lcn)`Pb3FwzY^jqU<@0(6Tj*dzx#O%zr`VuKn`tZoC(DLDPL)`+m zC6cP+Zr76~WzJTcQ9il$&4kJ}_0%=v$kC-4T1Nwar$g}#r%_$krTUbIiQ7oze4$&+ zZQTi+pUEKbO=eVBe(iG9RmDt5B>C#wYVo$q4lP*(wZRH+ zrl5L3_q0#TX3E4^{p{h5c-W0jdmYvfjQMO@g>_C3vcDxaeO&69Kz^g{Es%6ctVwD; z-G1z&vWp=nZe`kA_PV?Y)ld%x8A^v|;XTtGd1!3b`*oOr(eRl}k(TWQ)64~2=AeZf z55cNCjDv%dZMV3MIQ%1O*TfYnU>ud{Ph3_8?v0MyO;XF}c1^;ZCMqn?zd5<5^!}*z zC4P6om!m;_5C{ETp>5(Cl;tF)Bikd&zpT`AuxCWGFZywM@T8vY2jaMOTey_@rj=?vU3=p{LzIscl~+_PxrlDV%Q`{?nk^J$VE_zm@q0CrIsIA zwP+bzEz}cUS~XyG-aVa+I1=aFx$=Zo$c#U+bF8Pr>Ab@`Py_D?O+ycHl3UArBNX3* zP2OX|Yv)}lX!Nn5dLyNS7ntrTHnqJtLb1rzqC5?UE>D{FEAE~pdV?P zyRwx!p>cI(oAY4R{CItAII~dcog3dNCU-MI+sMZ+ccJoRPRFgiO&zy#aNNPfe1Et+ z=O7XT#Z{S*N@x4c^r~lD(lEh(pDJMoFiMx4;d6Bs-vgyjdE+))8w6a{CE}+x>*|<} zoS|Pe=jH~#x@@dH9W^z~{in^cB`m->*ZYyBI!-*s?)H9j?;)AOXhGq*wU&P*bvkfLDY#@|GMfS`@R z^9u_o;#G(0+Kzp+xVS_vXBsBk%{2++78X1u;o|h8Z=vDFH&`&Y_45%;BlD4- zGr#BeTZ0JnO=~^K#SqEq$(TkQxgWc3(4U1Epdf0C(7fWFsuv9HmYlSAkJbYl{ z7K)dlTsUpfMNPtM1D7b1_n+qkDA@KziEkFTjn3=1J^o)%xHeF26bjp0OnvXf`hhic zR5qSY3uD<6VC6)qeRp{n)U2z#AGqX?JQRi@v=M9H*c&y|G)uw`wmvqnRvMys%7wPx)6{(w5-;qnIMQ-ztHyG5xCEob<1dH-(jp0o zSY>?}sx+)SURG3DpgrB%v|8DWI!5z5M+Hd&Ew}xuGl3W@u_lZ?c|M<&b|>Bagp0m% zPMLhZP4kIW#U2K%w;OX~9>8ZZA9cLCB2_S*)nbgo(QVv{?PH4h8Ed5&xN=R$6?*4X zyDE?BIi~`nwF}0yn5!ijrUQky?;v&*)cBqbc)uvtXZQyodr@wbl%2<^|4FaMiC}MP z^XadZfSd~`-}HMMKn%tbXK9v1j&8VT)sY$`5>S4)Rd>7>)kfywG&WkLJIP_RFcDKR zxJ52)rp(`Bmh{ngM7-m{YOQUNS%1ZNwnpW|4@LtEMTH!!*&HxQ1>i3$6@ZR`iIAnW zca4)fOo8HjTb^C9qAlD+0SMd3lDFyP=_;JC@Nv52^x`S_KL8&IO+iTa3{Mh_k2tEF z%odm$)xVURSaHOy;;<-i#&;Xq$~;6JY>gt#BUD9%opABp_%!qs*%;$Mf%W@4Z%1`@ zI}j72oqVUV7bh^W*($d7)r`JWseNz|Km4kR=+Nxk4I@z(Sp7C$+23(IE{g3oY&KXN zQPLh&Oz_6AS#mi{p1r&zaB{K0V5yk7ng==Lvk)M?WJ^A(Jmm3tl^DL-T;e#& zx@nU0PS_*^4bD5yYUZo^W)0%yNB``S!6QN zwJP}WE!>OL*0vqL^SW(bnZ4;+)&XF@itjx8eWhR%AW3XjB)CXV7l<9D7uSaTtzP#J zFzJ$zh`4!9UT!0Ho?Z_vy{ZV2@;fw~rOyhbu4i-=aQefGM|1THBDfv$BDmlQCa3_r?f~IU`!}ZEQGfHG(1&2=nPQHN7qmnop zn5|LNffD=TMBKKL$@VSp7q%ZdXfz{THUvhC4U49)*i9!zOq`N)XysXY*tg_%emzsv zFV|h~AJlSMdPp{rv3w868Q@8go|C<=#xW|LLT6Xt9TC;H>V5Zb(Two&<5FbZB)QRX zQ$hS7&*?0{Tn<0#s(iA?WOfG(xe(~0%Pki*;4rduv=c7e+V0jX@64M2cVe7_++#** zJlPG-?T=cvr&obh4vr}aZFd?!4lvpfwdZnkw&Q74%PevOX9F!*&>qK~*@g@k>GB&_ zid70bmpe_(b+*TQjkj01AnS(hK|mpO0F3g}-#gozAk8*guLsVsk@ac2-7PXwY-(mz zJ%`6_P;#YPEPHnX!^1JY$K{m&HjV~o6+QYqlb~Pg2k6B1X4p_9Ys+DJKp}K&Y$~_@hGt49v#N0V| z7G&P?>@5#u=T~)B??!YhRM^y?#pub4SP{;|6?07-pLU{x0q&*I;dx-%g<+GxRlG00 z)xv4N^klc>9{p-`O{bF8o~p-T)fo&NB{j#ijOnT1eAVa0F3}zAJ4^`}JP_}P&^M&F zAKqlTwpro@!FfY^=1tbOiFx;p=PPOKO8Qq{x}un{8K4gc(Xpf+&?TL~_{QdSCdy|+ z%MT{T-4}M8#=?e&V>Vv6Z5Vk7@5JObE?V~3;i6*^(Lp`Wp+SCJK#MV?$JHJ!Z>z#$ z4xg;38($`OKMAhBUY=b(l|ba7svr~2A;aGw7F&5RCN}2OsU%hHpg*a&>LQ5r)qSv| z@#|eYsvs5lbndcb{2O#3TPAnbSBWZkl(|-vdHpZ-<0^|g19}RigsARvdCSKL^_6Cf z3dKlNyNlKzKOe;9dSDVK>VQ?xr_Kw5$6%6KtoD7{w_6W!$(XJZcE89`IlVFUu2CnG z7t$m75>eA3d{%F8qSWQYs@&qzG}i4sDedxs4hl)!W8~1& zx>U)xSO+J_h|Nw=)QmgnmUG|Q_p$&>Ddqyd{l)~tn0x)Fsg=o!n7#+UuXEY6;AAx!OaBwOR@qQLtu-qP+cTK8EWjl}g05wo4yd+BxOpPsc4 zDpU)d?3Hc#L`e*0n|r8dennILMJjOkn79+?`)(r$db--T(X#@FSK`Ui9+lHC9+8n9 z@2y=jlC820m}|fsH;#2SdCw>o64;w!*CNM1kgD+ZBVqT6eDybvgxa8Ra>^dPP*(REp{X~`sd{umQ~l?Lp=7k`BhOZ~xQ z-%+Am4gG|Wme!t7P&j+^O59v}D|zscq;~~YL6Xwx$i2Hb!8>?1PQSa@T{Mu82b+zK z^I(W}o7XR8URrn|fP6furF-=4cBT1Tk=IWYcTu9%-U)aJ$3uf;snP|O<*mKKU$Jwu zM)$|}-REwER~8yvgL*>iF`j%=tmquzZ+Q5!c+_a-*eLw%FCzVdQPCP~EDRqi#gR&G z(N-ND?=`a!{uGh;+Yn3Y5KVylU*z~-7c3|_XyA(hMFGFw{pSlWGg6b$yhiH&$DDQm zwqIbx+hJjmo6)R&WBE7VzzWd@9~pif^ZWV#bpc%=B4X$r#?$p-BmR;fXoiry;TY>J6k^) zP0w;(miQZ%c^=YbxZRL5fD8Ow1|6|Ur`I{JW%9>m7EX>Q&Ea*poE>;1jB>c0rw3qK zNc)jKvUbG>4e8>;{xXMle;Dq2(;^s+`HO!9%tyTdoKYXnt{ZFh7I#70(dBRsW+huJ zde(O4vp!zdHw5!RA?Xe77sN{MnLC4Q3&x=czqQ8U#+OgcZafpgm<#UqlXk7Sqa2zq zIkbgRd@443{AXje29f(g^&TUOy z_We>Czc9&kExt1e%fJ06yLjEg24o<~e1ctg!D}$3k~mO&DS!6%_VQpb;f1ojz{Yyc z&PuM!XIaQP!YYSv%fn__;>U-6OT~vlE`9P*$tzjPNLx6t+&sXRRvzIp*^aWhH5q&Gz_FMUYSu^TrB;GlXxr;+zLQ7tj)hpQMK~T&+aCV}_9UW~ zHrT~@s%Z6deeO+*8Lv{hIKsNtoDPCc5n+bm%E8nUZS#1=wxKGw@@KOjx~H}?)(M{y zj8^tz;53+zEx?T#60gZc*gjnBs*Q{3zWXPQ__}lq z#m+^hM5yaGEr2iD2X93e(r(&5n4~fefLV%!MSWZqFa6Y9JYi!J;MSlj=1|jEC+1>F zE99WVdrv;EqP2`aMcOBGKiKyF+;)J{@8^n>XiW%6;tDMg~5&QC2u1v=v^& z*bfzc-RI4Uw)?6-)yPQO!?MvF92*xaZ(5onG$i?VN+?0&r1(a)v#`I*@}HEW;w>*S zR@E2Wou`@_6N7<=$^tWe5)z31E7Fa4mZQbkw4+<}%?i#?QF5w_OuMHD+UrU)wi^@4 zR~QCk3~Rj`N-?Ks2837|dOIsFl2;*g#(jA7&7+qWo)d;e3}j-zBwz?q@!BG}@e*;m zW$_3pkUlCm82#SAO*LFHZm-NY=kjTDnSGYEro?*l)|KIG%hCIjozoj1j&>+~t;U50 zaqKma*UnCBTAXvLD!EoN6!ghAT1%bUmruqAK5Wzchi1s}6btTgX=Gjwcg^LAP>zp z4i}iS?+CcA(&kifYI*e5^WF~~I^Y(50lQqOHk2K>)Ee7@aeT7qp8QNa_3 z>Aq)E4Gs*1!#ikDYl9>(N}Q$&vDW$WP*F5)`iP@^dt>TN#_79BQhAZNH(iO1>E^=6 z<}NRu!xOLdGs?w?f$wik-8@ZrJvFChl&Vy8uT$G$;+n%L(k!4yInHM8Dik!9S{D}d zdX%v^?i4DC>GCM1<=vVTn|goqXl_`)J^@*GZ-GYBm8ZD$9^-L3GROxjC)Os-3~cdtH$jGPvNawY?M)ET*>Yn+o=x@z0#ri)Kk%!#F$RSdh{D z8{^M5^{a7mDufuv!*pMH$!;yon|n~+x2l$Mhi?m-?~j_6Ze6v*yR0Ev$+s5p>`3Ln zcg4z)NyKqOJ;9^eE|`sfa{sZw*+*e>gSSq&y_zs~CN1`|6ALTp;!463(-_1Iua2#230 zt54`?Oc%qeOS!&$`&dVM{uNHI%SOLjrH>O%xNejX|0<%iz#KjPE0Rlq?-UjPO!eSa zEmdi~GK%=CRWE#m=5`~43d}sZVcj>UB#(fjRHho4YVK}Zfl^(*AuBpA*@ws1f7l;0 z94zwmCH(+s18&7(PYY&m-nF=K7lVQUMgsWp9!&eg1sodpMaH@b7t1(ViTy81!NKpm zr!i>UXJPf0{Lxf=;|6*$gW-gvLbEjwONr@U`l8IPDfj$Kc;m!-5vD+TeB`RyOx+MX zP&!atuR5mgz68P-^XnNu_Ki2x3Sv|7xefCYJ=?yPx9GHWdh5dKeXl24eEHN#a5l|Y z2e?FfV5UjZI>g^KzAwU9mn8f1p|Ckiix>p`7RTmth|2BYxU;cF2~e&bsbcW8t)z}v zmo_SPXO@HzXLN4e6joVz6MO#kK_TViqtL|0m*!_D$XxkBdDDrLJ9sB;m^d^C0dDoG znpQ!wx5>}5dRTYhOBGXQlAKo|6g5~dKpw)@sH;vI#_R5dkJDUn-}NyVO{Q??wl%3< z?(Cox=?}79p?S+VEa_%jkc-IH^pW$$$Aize$*do7nK0XDx*cG8$fh`%KPcV4_%~m% zofDY-CAS;ZN7b6<=s0U!&QS(07IiAi7!v0uBV0;Z1F_hNe?IdDJJZ=riOqKn9ZT6C zdRhIN_(%C@)fA;vf_CS%YQc@L-P+BF)GJhhVm5DgPh8xbM{|cIFM#PrWo!`_j8`#A ze0DtGwq+iBKDx1Xch~iI7|kpuR(eN$9+tw=&A@>b(1E)2MdwwzXO0 zp<-#mC++g$sWS06(hK;j+Vz}a4#0HkA5_ZA_|K$WVpYw=vK%QiU1XkRgwoMNeCRXr z$K&;DxsvIG=0_<~dYLA~*1^F{eALMeU+G#8g{NVINY*d>?N()b-9+a_{F2LIf}$2h z4HuTy$L)u2VT%auzJdo^9*AyQP_c!?ncbrOM#AlS987=5mp~3t0N=IJ^cB~3)(SwZ z-^O(1@fS3+5UT4Ezj6XQoMkMQ&gq5xRrSzy9i#6?WV$l56w5w6mQ9h5qkeMcEQVZb zA$e~)va_g-g&&T4!praa^7Ie_~Cm7S=FI-0~dT$>!7$IEsPTuucU@~@6s&FiZIS}`R&_xo zsYf7CnT)rkj`jos-rfbF$`c4@wUF?5(NvfFk`0`#VyENdbu6Y>^EUnRK`hdixU<4w z@i<+)vknYAG8xIsRW1S01lKB*?!M&2o?Xr3r0NbI7VAVdr~$rdAhFvRV2E}cJ6#gY zDRsY7X7P9b(j*3QEE_q%0ZMT0YSdtty1zr28SRo^{%2Yah(L~|nyYd^gnUsnOt_fwP6;&oz|mv~FT zMs82nPi#vC$)`oSDqZXp6pBo?5KH+Oz!S{mxGBybqc6sLKxz=I6CEpVH)I)JChR|; z?GV#tTp4;$C=mKMudp+Alwveg7L(keBYID@TO@gi`1ykwCL6ot7)gA>@qwl2)yVCU z6+6ScfWK-yB9nXHmqlcW-{VR6k(`j4ari9SKF{!@<9U2 zjRI81*{MJ6Vz`z&3?u<$wm$4R=ipQ|FVGHEtGVY57%zB#>YwJ(n|r{8wKzX|1^2Be zm!NEi_KY8AyKIUWYh!7MlqYl#XLqfaK1-`&GGNHeFxQ|g&mR|9V;PyVV}4HAa6k46 z0VkuwZ_ktMg8#g0d2K z8TS;vbVTks^gv$n?U)QKy=MP;3mGQ}c&DQjF|aZ(zUsA|Q@UKrC@;}lU_5w|lJEZ2 zGxBAMp-lLo(}N8m$gAbH$1ej0CwHF-?D=P4V20MJzC+Ky5kyF-flE$bFBiKUO0OGRn)b?J_D3XZzhiD&Zqup@0EJn2jd8Z>8q@Ed-uD$? z7zx@#yr?Q&f=&0CJ>~q&ezIJ`pX|g2a1;NbCZ%3=d?wPRu%shK?H=-EKV0(V329J6 zcG1(u{e(?1oew$5>&-rcH$6^2*7a+&!m5#0Wm%>7g{2it{zG_zfctX6y1!*CQF0JO zmKe=4N)7klWZMOOk88owy!z46akDNw356!(u9h4$+2Z7uue+5Ed;1*Ed7ExCU+Bl1 zbVZ(+HMr{7G)(rIBSBs-7@A;P?~4n^dFiO_7H0<#Ns6;t+#0sD{QNAEa=t>0b62-M zM8|agBHQjtx!H2AoeeBPWm>c}NPj;%^meY#C{FlJ@7o6cWetgEN>fGZKXCj9`?o}mMF09B4pNaf@5K^ zpI~CQEcBcwG&dYYA}-t*?~=u}9LW^w_V)2p%j$!hPA8d~cDRWbNR(-P-i%w&Vbv;< z1z7k9u{O($k+h6mKWpyH#s|jX!C-4?Zu@{l?=-Apt{Vs(#YmyHol;=$b6y6~<3pLL zH7DE^w&^90>i6Q(2t`ty9!V0Y^i@oXM@^ziz-M2I(Xs zb|-9Q&l*XGF`h4=4{NDL!h<;0ae3~#UK+F zcA~*IlIx){?{?cuQ5sG91N>j{{s3!yr-9)pPfBOf=DopScSpkyK+9#7Bxqmy zfsHOR3|WZ*v#75=#3mIr3hu5Zjx{{R|H&v}( zyo}(U#Ca<&DA?8_w_&rU!pM92g7%72%WF&@fpkS#inFcQ&9S6UQ$smx5d_bVkEu6a zye@qgh%(Hm;CTvUJm>1^Wp?uB$R&Eb!OwZQPpw|O78NU%yVdg0RiGMWx=zc;?Jx0) zeCcL=B7{&I^qr|H)dflRE`#NG^XxdH4g_+|j>d=@tl!P7`f&Vwq-#fij(IsTb#he4 zSv^gHT8>>^pfFx5a@|Q-T_@+DMK6V?SA*OgSsqna;V^-Zxn80~8G_K}bNd=Kg-T{| zQL>~^Uba&t86U90w*P5MezPXS#V+Igi}_q`H-s%pta~Os&cx4xNo|JIJg5nTcS)vZ zXh+#>*Lt|xqLKEFo4TNC3v=EV<$}G|kmdUE7HAPj^Q0G(tI$FOy-+SQ${BLq1B1%k zM=}o^uAa^5+a;YWl4QVOi_Umok9rvzedq(lI0bpcb_2!jk}27gm-~ujQi)Ra{RjhR zLikbI(fQ4xUe%^$sI6peojbxG4;2&64q<*3r#aEqYqsviQU_tR|H3wBY z!&=W|OP(!9s4+TCBbUZ@te7Lu{Crm*+3HHzuU2ma>TkCe^uV><`;k{qdDKRXR`Ba< z&?@UPwJ=qpFLK*!&GnK|crdPVm7OM@YdDvl0kTVIU$Rf*?nJvqSp4fG&h=swhh0yYFZcBn1%I`A|?G|p>XkA7K#@Qia_q( zeC=(b{+R0;VZ8&q_6{n~M8&e%&*^dNWM{pgj;pkLV1Tsi;zmL}zixHMw6NW>;==yt zJaaJYbzOMsGcx$y%#%{PWJh-EFA48PEguc88)#}D9J|i*jt7@JY+SUep6bg*7E>=2 zq{hVzDu(kY)z-aL5W8NAIoRJ!1_Elde7iMPrn+lC!XYXZ2s_FmqjheinQEbYOXk_TSz$dSaBdqq7bKWtMdVCyu zp~S8&!0l=@)H^jOj=V!6ZEeEk1+?OgUQ>3hLmfx)k_xNN?9w>9y0VpQrPZJtu(wJc z?HzLP0+Vip{_ytPRe3>@>LlAm#napE)1|sjcJi;{+~B&=)4S&QQhpSiQWGt&2%9ly z?|)s4p(eY_k_C-^Z`CG6_;T(%A(LgTG;0KORGr^9qvPoA(8mXx(#`TAdETm-kKf6r z^1AF-5QUExTaq}>uQ$$BiE}*uEKthWh1+78{QR>L)LMA@sl?l=k43%llwz{`IhnBkk&~L#OFf2D$;}0In5CUVjeWq~yDG25$t(8_ zk*ZC-9$BGnGHI#Ui(|usqAQPIO}WzghjNn^QQwXaT!}|1>Ly{4p$pgNJf7&ruBfu0 zLGVczhw|Jg^WEbvTzseUUm)J4}Dz*Rg|*3*9a za!Z7;lL(rh8)nMsp1IS~mV$$Fe@id^#Yz2*E-$blK!tTf_;0WO&AorV@RA1Zpz&C}Td#ArYHUNOFE_D-vZGh7zhlGdVQnFy)kEDA`F45hv>;%PWPd$3mO*AIHHg~a-g zgVW7`AhcEwvQK;812MEzQj&Ry<^e1M$&;kVj86xcUfFrFkG=3z1rAUUODZ(L;*Rm& zwGd`C;?fQ+wQ@%apASVO()IZX)@G*6p|sHf^N$q|yyl2H1a0Uac)u9co{`gqydl{hSw{u4~o%@@zSh9)20=M_voe1jFon_9dT2J^s>G z@G3(4igYYWHSb9J9-@E!w8}cG6f~Y*0-;j9=**X|Grw zGIEMOU-Al+olSLbh45#ZG>&~9Y7{AtvjSEHU^ICGoPfzWNyv5^tbL*VCT)yOhF!T- z(amNh2Um&7xWrHB`@5_<<%q4niueVyaY{^OF4;5#<&suZtXIb`{0w!DW6aq_@CDh> zheYe!%y%kYgZu@uWr4If4=hPnabU)C&K3H z65}L8y%)SI)hJ0PD%4AenrVS@K$Vj@ESp&})~#e%6^!7kSL&l4YpB&s!m&Fio}gl4 zBP4Y7GmSd0HqSx=Rev#laI|spUXX>0fQquprR~WLH}OP1nDhWnWZ*j-2aq|+(6OF0 zp^r>_iY=6I#6ij6O=SI7dEl^z@7Wy*I<{r3pa|i|j8Hv9{oAsG72Kpo_+nu~pYFzawM#-tc=bve6<6YGj zpQu!?IkSzB(S1lA?m}GpO-r+hQ>Z(*YDQo z9k;%}nt>pT3%GK;OsG1g;{yV1S@BHz9E z-OP%B`fA+E44-3^HcBfUuh4k~6m6LYO-y?=1=ML?H~HX}s$yjo_(w`}U4QMq>s}i{ znIF)zuZD8q#P*uwtq$CImmoComz56hu`$q}7E1Tl6D=>ICQVJ;|HQzrLzB(^%K_hm z6p>Jkg2p9jH&!AX|SCu_n5{Vx_4eo@%V@u1`E#hn@ zP4cJTGY%WLHNU7k=L*~d)pIe?*3#a#Hc7Aw7%$+ZvJ=W`#rlnz$)D&#i%Ps$dm;DCdr0%x>$d!R_bG!@+Z1OrYGA zsb_Bv+qqe?N1nMDj*)mmxTTWbBH=il{Nw2$;H5`U4>hM;gm6d}rz5iQ< zw4Qul8gI~PGQrOAdVMx!chiVgw2Tk}D;o;$9F6hk$QQV?d2%Fc?8~G(>y8;j+8TU` zs&>*fz476~5~-NXT1RZslx{He9%){TtD;8qoBwJ998|!OZXrSfu*G99-xz=w=@OVc zA4CNTJx-F%343~ZF)jc*C=$?I(cZge#;&3xh4jKLS*`M1;qzU(yvu%j6w@k1wci8* z?AKsBeyI5?83g}8v!Gx8APoU({eP0iNRXzca;?j? R(ZogIXP{@aE0bt@<}dH2nic>6 literal 0 HcmV?d00001 diff --git a/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb b/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb new file mode 100644 index 0000000..e8ad32f --- /dev/null +++ b/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb @@ -0,0 +1,882 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0122416a", + "metadata": {}, + "source": [ + "# SC26 DragonHPC Multiprocessing, Native, and DDict Tutorial\n", + "\n", + "**Estimated time:** ~30-45 minutes \n", + "**Format:** 6 short exercises - each has a problem and a hidden answer you can reveal.\n", + "\n", + "---\n", + "\n", + "## What you will learn\n", + "\n", + "This notebook introduces Python multiprocessing with DragonHPC for single-node\n", + "and multi-node runs. You will practice how to:\n", + "\n", + "- launch processes\n", + "- synchronize worker execution\n", + "- communicate data between processes\n", + "- observe process placement across nodes\n", + "\n", + "The exercises are beginner friendly, while also connecting to concepts that\n", + "intermediate and advanced users already know from Python multiprocessing.\n", + "\n", + "---\n", + "\n", + "## Setup - run this first!\n" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "fc68fa9d-cd2d-4056-94df-040ecd062dbe", + "metadata": { + "scrolled": true + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "info={'node_index': 0, 'gs_qd': 'BV8AAAAAAAAAAgAAAAAAAAA3AAAAAAAAAAAAAAAAAAAAcfNluE+0TwcFLtd6GM2leAAAAAAAAAAA4NjABAAAAAAvREQwMDAxMzVpbmYwTQADAIAAAAAAAAAAAAAAAAAACOABAAAAAAA=', 'ls_qd': 'BV8AAAAAAAAAAAAAAAAAAEA3AAAAAAAAAAAAAAAAAAAAcfNluE+0TwcFLtd6GM2leAAAAAAAAAAA4NjABAAAAAAvREQwMDAxMzVpbmYwTQAAACAAAAAAAAAAAAAAAAAACOABAAAAAAA=', 'default_pd': 'AAAAAAAAAEBx82W4T7RPBwUu13oYzaV4AAAAAAAAAACA6QAHAAAAAC9ERDAwMDEzNWRlZjBNAA==', 'inf_pd': 'AAAAAAAAAABx82W4T7RPBwUu13oYzaV4AAAAAAAAAADg2MAEAAAAAC9ERDAwMDEzNWluZjBNAA==', 'rt_uid': '8693580160732442117', 'auth_token': 'c047cb39c9de6919a17499113a4cfcace0aead0f9c1bd8036411a6a1d95be510'}\n", + "Dragon multiprocessing ready.\n" + ] + } + ], + "source": [ + "import os\n", + "import socket\n", + "import time\n", + "\n", + "import dragon\n", + "import multiprocessing as mp\n", + "\n", + "# Shim for this tutorial environment; eliminated in future Dragon release\n", + "import dragon.workflows.runtime as runtime\n", + "dragon._patch_multiprocessing()\n", + "dragon_rt = runtime.start_local_runtime(timeout=5)\n", + "runtime.attach(runtime=dragon_rt, auth_token=dragon_rt.auth_token)\n", + "dragon.native.pool.current_process = mp.current_process\n", + "\n", + "mp.set_start_method(\"dragon\")\n", + "\n", + "print(\"Dragon multiprocessing ready.\")" + ] + }, + { + "cell_type": "markdown", + "id": "bfb17bfe", + "metadata": {}, + "source": [ + "`multiprocessing` synchronization and communication objects (for example\n", + "`Queue`, `Event`, `Lock`, `Value`) happily work with `\"dragon\"` set as\n", + "the start method in `multiprocessing` just as they would with any of the\n", + "other start methods in `multiprocessing` (i.e. `\"spawn\"`, `\"fork\"`, or\n", + "`\"forkserver\"`).\n", + "\n", + "When the Dragon runtime is available, a number of opportunities for\n", + "optimization arise which is why there are additional tools available\n", + "in the `dragon` module. After exercising the use of Dragon through\n", + "standard `multiprocessing`, we will begin by introducing the Dragon\n", + "Native `Process` object which exposes further control over the creation\n", + "and placement of processes, noting how it intentionally mirrors the\n", + "familiar multiprocessing API patterns." + ] + }, + { + "cell_type": "markdown", + "id": "03fdc111", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 1 - Parallel map with multiprocessing Pool\n", + "\n", + "**Background:**\n", + "\n", + "`multiprocessing.Pool` is useful when the same function should run over many\n", + "inputs. With Dragon configured as the multiprocessing backend, you can use\n", + "`Pool.map` for data-parallel workloads executing across many nodes and all\n", + "communication will travel over Dragon's HSTA (High Speed Transfer Agent).\n", + "\n", + "Ref: https://docs.python.org/3/library/multiprocessing.html#introduction\n", + "\n", + "Demo pattern:\n", + "\n", + "```python\n", + "def double(x):\n", + " return 2 * x\n", + "\n", + "with mp.Pool(processes=4) as pool:\n", + " out = pool.map(double, [1, 2, 3, 4])\n", + "\n", + "print(out) # [2, 4, 6, 8]\n", + "```\n", + "\n", + "**Your task:**\n", + "\n", + "1. Write a function `transform(x)` that returns `x * x + 1`\n", + "2. Use `mp.Pool(processes=4)`\n", + "3. Call `pool.map(transform, data)` where `data = list(range(12))`\n", + "4. Print the mapped results\n", + "5. Print the sum of the mapped results" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "ef13d43c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "[1, 2, 5, 10, 17, 26, 37, 50, 65, 82, 101, 122]\n", + "sum: 518\n" + ] + } + ], + "source": [ + "# -- Exercise 1 -- your code here -----------------------------------------------\n", + "def transform(x):\n", + " return x * x + 1\n", + "\n", + "data = list(range(12))\n", + "\n", + "with mp.Pool(processes=4) as pool:\n", + " mapped = pool.map(transform, data)\n", + "\n", + "print(mapped)\n", + "print(\"sum:\", sum(mapped))" + ] + }, + { + "cell_type": "markdown", + "id": "b7fcc5f5", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def transform(x):\n", + " return x * x + 1\n", + "\n", + "data = list(range(12))\n", + "\n", + "with mp.Pool(processes=4) as pool:\n", + " mapped = pool.map(transform, data)\n", + "\n", + "print(mapped)\n", + "print(\"sum:\", sum(mapped))\n", + "```\n", + "\n", + "Expected mapped output:\n", + "```\n", + "[1, 2, 5, 10, 17, 26, 37, 50, 65, 82, 101, 122]\n", + "sum: 518\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "d8e54e8b", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 2 - Launch processes and join, using queues to communicate\n", + "\n", + "**Background:**\n", + "\n", + "A `mp.Process` is started with `start()` and waited on with `join()`. This is the\n", + "first basic building block for parallel programs though in contrast to the\n", + "prior example employing `mp.Pool`, the return values from target\n", + "functions are not collected and returned to the caller. This motivates the\n", + "use of `mp.Queue` for process-safe message passing which, among many other uses,\n", + "feels like an especially natural fit for producer-consumer code patterns.\n", + "\n", + "By setting `multiprocessing`'s start method to `\"dragon\"`, all of these tools\n", + "from the `multiprocessing` module will leverage the Dragon runtime. But Dragon\n", + "also offers tools to unlock opportunities for optimization, tuning, and\n", + "control that `multiprocessing` does not. The first basic example of this is\n", + "the Dragon Native process object, `dragon.native.Process`, which supports the\n", + "standard `mp.Process` API but expands on it as we will see in a later exercise.\n", + "\n", + "Here is the core Dragon Native process pattern:\n", + "\n", + "```python\n", + "def hello_worker(name):\n", + " print(f\"hello from {name}, pid={os.getpid()}\") # stdout is not generally a best practice for collection\n", + "\n", + "p = dragon.native.Process(target=hello_worker, args=(\"dragon\",))\n", + "p.start()\n", + "p.join()\n", + "```\n", + "\n", + "Here is the core pattern for `Queue`:\n", + "\n", + "```python\n", + "q = mp.Queue()\n", + "\n", + "def say_hello(q):\n", + " q.put((\"msg\", \"hello from worker\"))\n", + "\n", + "p = dragon.native.Process(target=say_hello, args=(q,)) # mp.Process works here too\n", + "p.start()\n", + "message = q.get()\n", + "p.join()\n", + "print(message)\n", + "```\n", + "\n", + "\n", + "**Your task:**\n", + "\n", + "1. Write a worker function `square_worker(i, q)` that accepts an `int` i and `Queue` q, constructs a nicely formmated `str` containing the worker id `i`, PID, and `i*i`, and places that string into the queue.\n", + "2. Launch 4 processes using `dragon.native.Process` (though `mp.Process` would also work; try both?)\n", + "3. Start all processes, read and print the 4 messages placed into the queue by the workers, then join all processes\n", + "4. Print `All workers finished` at the end" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "29b212cc", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "worker=0 pid=52321 square=0\n", + "worker=2 pid=52323 square=4\n", + "worker=1 pid=52322 square=1\n", + "worker=3 pid=52324 square=9\n", + "All workers finished\n" + ] + } + ], + "source": [ + "# -- Exercise 2 -- your code here -----------------------------------------------\n", + "def square_worker(i, q):\n", + " q.put(f\"worker={i} pid={os.getpid()} square={i*i}\")\n", + "\n", + "q = mp.Queue()\n", + "procs = [dragon.native.Process(target=square_worker, args=(i, q)) for i in range(4)]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "for p in procs:\n", + " print(q.get())\n", + "\n", + "for p in procs:\n", + " p.join()\n", + "\n", + "print(\"All workers finished\")" + ] + }, + { + "cell_type": "markdown", + "id": "f35a5475", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def square_worker(i, q):\n", + " q.put(f\"worker={i} pid={os.getpid()} square={i*i}\")\n", + "\n", + "q = mp.Queue()\n", + "procs = [dragon.native.Process(target=square_worker, args=(i, q)) for i in range(4)]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "for p in procs:\n", + " print(q.get())\n", + "\n", + "for p in procs:\n", + " p.join()\n", + "\n", + "print(\"All workers finished\")\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "1975b9da", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 3 - Phase synchronization with Barrier\n", + "\n", + "**Background:**\n", + "\n", + "A `Barrier` blocks each worker until a fixed number of participants arrive.\n", + "This is useful for staged workflows where all workers must reach the same\n", + "checkpoint before continuing together.\n", + "\n", + "With Dragon, `Barrier` objects work in single-node or multi-node\n", + "execution environments.\n", + "\n", + "Demo pattern:\n", + "\n", + "```python\n", + "barrier = mp.Barrier(2)\n", + "\n", + "def waiter(barrier):\n", + " print(\"before barrier\")\n", + " barrier.wait()\n", + " print(\"after barrier\")\n", + "\n", + "p = dragon.native.Process(target=waiter, args=(barrier,))\n", + "p.start()\n", + "time.sleep(0.5)\n", + "barrier.wait()\n", + "p.join()\n", + "```\n", + "\n", + "**Your task:**\n", + "\n", + "1. Create a `Barrier` named `phase_barrier` with 6 participants (5 workers + parent)\n", + "2. Write worker code that prints `ready`, waits on the barrier, then prints `running`\n", + "3. Launch 5 workers\n", + "4. Sleep for 2 seconds in the parent and then call `phase_barrier.wait()`\n", + "5. Join workers" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "dbf19fcd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Parent arriving at barrier\n" + ] + } + ], + "source": [ + "# -- Exercise 3 -- your code here -----------------------------------------------\n", + "def staged_worker(worker_id, phase_barrier):\n", + " print(f\"worker={worker_id} ready\")\n", + " phase_barrier.wait()\n", + " print(f\"worker={worker_id} running\")\n", + "\n", + "phase_barrier = mp.Barrier(6)\n", + "procs = [dragon.native.Process(target=staged_worker, args=(i, phase_barrier)) for i in range(5)]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "time.sleep(2.0)\n", + "print(\"Parent arriving at barrier\")\n", + "phase_barrier.wait()\n", + "\n", + "for p in procs:\n", + " p.join()" + ] + }, + { + "cell_type": "markdown", + "id": "f8f3674b", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def staged_worker(worker_id, phase_barrier):\n", + " print(f\"worker={worker_id} ready\")\n", + " phase_barrier.wait()\n", + " print(f\"worker={worker_id} running\")\n", + "\n", + "phase_barrier = mp.Barrier(6)\n", + "procs = [dragon.native.Process(target=staged_worker, args=(i, phase_barrier)) for i in range(5)]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "time.sleep(2.0)\n", + "print(\"Parent arriving at barrier\")\n", + "phase_barrier.wait()\n", + "\n", + "for p in procs:\n", + " p.join()\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "90e25403", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 4 - Control CPU affinity with Dragon Policy\n", + "\n", + "**Background:**\n", + "\n", + "Dragon `Policy` lets you control affinity. For CPUs, use `cpu_affinity`.\n", + "For example, `Policy(cpu_affinity=[1])` requests placement targeting CPU 1.\n", + "A `Policy` can be used with `dragon.native.Process` but not with `mp.Process`.\n", + "\n", + "Demo pattern:\n", + "\n", + "```python\n", + "def report_affinity(out_q):\n", + " out_q.put((os.getpid(), os.environ.get(\"CUDA_VISIBLE_DEVICES\", \"unset\")))\n", + "\n", + "q = mp.Queue()\n", + "pol = Policy(cpu_affinity=[0])\n", + "p = dragon.native.Process(target=report_affinity, args=(q,), policy=pol)\n", + "p.start()\n", + "print(q.get())\n", + "p.join()\n", + "```\n", + "\n", + "**Your task:**\n", + "\n", + "1. Create two policies: one for CPU 0 and one for CPU 1\n", + "2. Launch two workers with those explicit policies\n", + "3. Each worker should report `(rank, pid, CUDA_VISIBLE_DEVICES)`\n", + "4. Print both reports\n", + "\n", + "If your system has fewer than 2 CPUs, use CPU fallback and still run both\n", + "workers (the environment report may be the same)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "93054056", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "(1, 52538, 'unset')\n", + "(0, 52537, 'unset')\n" + ] + } + ], + "source": [ + "# -- Exercise 4 -- your code here -----------------------------------------------\n", + "def affinity_worker(rank, out_q):\n", + " out_q.put((rank, os.getpid(), os.environ.get(\"CUDA_VISIBLE_DEVICES\", \"unset\")))\n", + "\n", + "q = mp.Queue()\n", + "num_cpus = mp.cpu_count()\n", + "cpu0 = 0\n", + "cpu1 = 1 if num_cpus > 1 else 0\n", + "\n", + "policies = [dragon.Policy(cpu_affinity=[cpu0]), dragon.Policy(cpu_affinity=[cpu1])]\n", + "procs = [\n", + " dragon.native.Process(target=affinity_worker, args=(0, q), policy=policies[0]),\n", + " dragon.native.Process(target=affinity_worker, args=(1, q), policy=policies[1]),\n", + "]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "for _p in procs:\n", + " print(q.get())\n", + "\n", + "for p in procs:\n", + " p.join()" + ] + }, + { + "cell_type": "markdown", + "id": "aa55840e", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "def affinity_worker(rank, out_q):\n", + " out_q.put((rank, os.getpid(), os.environ.get(\"CUDA_VISIBLE_DEVICES\", \"unset\")))\n", + "\n", + "q = mp.Queue()\n", + "num_cpus = mp.cpu_count()\n", + "cpu0 = 0\n", + "cpu1 = 1 if num_cpus > 1 else 0\n", + "\n", + "policies = [dragon.Policy(cpu_affinity=[cpu0]), dragon.Policy(cpu_affinity=[cpu1])]\n", + "procs = [\n", + " dragon.native.Process(target=affinity_worker, args=(0, q), policy=policies[0]),\n", + " dragon.native.Process(target=affinity_worker, args=(1, q), policy=policies[1]),\n", + "]\n", + "\n", + "for p in procs:\n", + " p.start()\n", + "\n", + "for _p in procs:\n", + " print(q.get())\n", + "\n", + "for p in procs:\n", + " p.join()\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "146c2f10-2ec6-4f63-95b9-a75f7447fd0f", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 5 — Create, write, read, and destroy a `DDict`\n", + "\n", + "**Background:**\n", + "\n", + "A `DDict` is Dragon's **distributed in-memory key-value store**. It looks and\n", + "feels like a Python `dict`, but the data lives across **one or more manager\n", + "processes** that can span multiple nodes. The best part is that the organization\n", + "of the data is transparent to the user. When user code interacts with it, the\n", + "code does not need to know the location of any key-value pair stored in it.\n", + "\n", + "\n", + "\n", + "Key characteristics:\n", + "- Standard `dict`-like interface (`d[key] = val`, `d[key]`, `del d[key]`, `len(d)`, ...)\n", + "- Values are transparently serialized with `cloudpickle` or a pickler of your choice\n", + "- Data is shared safely across **multiple processes** without locks\n", + "- Supports **checkpointing**, **persistent keys**, and **filtering** \n", + "- Other functionality not covered here like **broadcast puts** and **batch puts**\n", + "- Data is automatically balanced across all the managers\n", + "\n", + "Instantiating and using an empty `DDict` object is as easy as:\n", + "\n", + "```python\n", + "from dragon import DDict\n", + "\n", + "d = DDict()\n", + "\n", + "d[\"greeting\"] = \"howdy\"\n", + "d[\"meaning\"] = 42\n", + "print(len(d)) # 2\n", + "```\n", + "\n", + "**Your Task:**\n", + "\n", + "1. Create a `DDict`\n", + "2. Store `{\"cat\": 1, \"dog\": 2, \"bird\": 3}`\n", + "3. Print all keys by iterating over `d.keys()`\n", + "4. Check whether `\"dog\"` and `\"fish\"` are in the dictionary\n", + "5. Delete `\"cat\"` and confirm the length dropped to 2\n", + "6. Use `d.get(\"fish\", \"not found\")` and print the result\n", + "7. Destroy the dictionary (to release its allocated memory)" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "435a7f82-d8e9-4ba7-8d04-5c72ebcd9bca", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "keys: ['bird', 'dog', 'cat']\n", + "dog in d: True\n", + "fish in d: False\n", + "len after delete: 2\n", + "not found\n" + ] + } + ], + "source": [ + "# ── Exercise 5 ── your code here ─────────────────────────────────────────────\n", + "d = dragon.DDict()\n", + "\n", + "d[\"cat\"] = 1\n", + "d[\"dog\"] = 2\n", + "d[\"bird\"] = 3\n", + "\n", + "print(\"keys:\", list(d.keys())) # ['cat', 'dog', 'bird'] (order may vary)\n", + "print(\"dog in d:\", \"dog\" in d) # True\n", + "print(\"fish in d:\", \"fish\" in d) # False\n", + "\n", + "del d[\"cat\"]\n", + "print(\"len after delete:\", len(d)) # 2\n", + "\n", + "print(d.get(\"fish\", \"not found\")) # not found\n", + "\n", + "d.destroy()" + ] + }, + { + "cell_type": "markdown", + "id": "fe0ec91f-7c22-4898-88fd-d3a2176903fa", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "d = dragon.DDict()\n", + "\n", + "d[\"cat\"] = 1\n", + "d[\"dog\"] = 2\n", + "d[\"bird\"] = 3\n", + "\n", + "print(\"keys:\", list(d.keys())) # ['cat', 'dog', 'bird'] (order may vary)\n", + "print(\"dog in d:\", \"dog\" in d) # True\n", + "print(\"fish in d:\", \"fish\" in d) # False\n", + "\n", + "del d[\"cat\"]\n", + "print(\"len after delete:\", len(d)) # 2\n", + "\n", + "print(d.get(\"fish\", \"not found\")) # not found\n", + "\n", + "d.destroy()\n", + "```\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "2de80c25-b9bd-4643-b24d-19a3530488fa", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Exercise 6 — Sharing a `DDict` across processes\n", + "\n", + "**Background:**\n", + "\n", + "A `DDict` is serializable (`pickle`-able). Passing a `DDict` to a distinct process does not cause an expensive transfer or serialization of any its contents (the keys or values). Instead, that process will share the **same** `DDict`, capable of being accessed or mutated by both child and parent.\n", + "\n", + "When instantiating a `DDict` object, you may specify the number of managers and nodes\n", + "on which the `DDict` will hold its distributed data. A `DDict` automatically starts\n", + "up a specified number of managers and an orchestrator (not shown in the picture) and\n", + "user client code interacts with these processes to transparently provide you with a\n", + "distributed key-value store that can scale to any size and automatically distributes\n", + "your data evenly across all the mangers.\n", + "\n", + "\n", + "```python\n", + "import dragon.native\n", + "\n", + "def worker(d, key, value):\n", + " d[key] = value # writes into the shared DDict\n", + " d[\"hello\"] = \"world\" # keys and values don't have to be passed to child proceses\n", + "\n", + "d = DDict(1, 1, 32 * 1024 * 1024) # DDict(managers_per_node, n_nodes, total_mem_bytes)\n", + "proc = dragon.native.Process(target=worker, args=(d, \"x\", 99)) # or use mp.Process\n", + "proc.start() # starts the process\n", + "proc.join() # waits for the process to exit\n", + "print(d[\"hello\"]) # and then prints world\n", + "d.destroy()\n", + "```\n", + "\n", + "This tells Dragon to instantiate and bring up a `DDict` with `managers_per_node * n_nodes` managers. The `total_mem_bytes` is spread across all the managers. For more information on creating `DDict` objects [see the DDict API](https://dragonhpc.github.io/dragon/doc/_build/html/ref/data/dragon.data.DDict.html#dragon.data.DDict). \n", + "\n", + "- `managers_per_node=1`, `n_nodes=1` → one manager, single node\n", + "- `total_mem_bytes=64*1024*1024` → 64 MB pool\n", + "- Remember to call `d.destroy()` to release resources when finished\n", + "\n", + "\n", + "**Your Task:**\n", + "\n", + "Write a function `count_words(label, text, d)` that splits `text` on spaces and stores\n", + "`d[label] = count` as a count of the words in the supplied text.\n", + "\n", + "Hint: Calling `s.split()` on a `str` object `s` in Python will return a list of all the space \n", + "separated *words* of the string.\n", + "\n", + "Then:\n", + "1. Create a `DDict` (2 managers, 1 node, 64 MB)\n", + "2. Launch **3 processes**, each calling `count_words` with a different song lyric\n", + "3. After all processes finish, print every key-value pair in the dictionary\n", + "4. Destroy the dictionary\n", + "\n", + "Song lyrics and associated labels to use:\n", + "```\n", + "(\"never gonna give you up never gonna let you down\", \"rick\")\n", + "(\"hello is it me you're looking for\", \"lionel\")\n", + "(\"cause I'll be rocking this party eight days a week\", \"beastie\")\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "098b4e60-63d1-4626-89f1-97ca635b9f13", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " rick: 10\n", + " beastie: 10\n", + " lionel: 7\n" + ] + } + ], + "source": [ + "# ── Exercise 6 ── your code here ─────────────────────────────────────────────\n", + "lyrics_and_labels = [\n", + " (\"never gonna give you up never gonna let you down\", \"rick\"),\n", + " (\"hello is it me you're looking for\", \"lionel\"),\n", + " (\"cause I'll be rocking this party eight days a week\", \"beastie\"),\n", + "]\n", + "\n", + "def count_words(label, text, d):\n", + " d[label] = len(text.split())\n", + "\n", + "d = dragon.DDict(2, 1, 64 * 1024 * 1024)\n", + "\n", + "procs = [dragon.native.Process(target=count_words, args=(l, t, d)) for t, l in lyrics_and_labels]\n", + "for p in procs:\n", + " p.start()\n", + "for p in procs:\n", + " p.join()\n", + "\n", + "for k, v in d.items():\n", + " print(f\" {k}: {v}\")\n", + "\n", + "d.destroy()" + ] + }, + { + "cell_type": "markdown", + "id": "31d72121-7b06-4a8e-a7a4-dd1c8a6b0b6a", + "metadata": {}, + "source": [ + "
\n", + "▶ Show Answer\n", + "\n", + "```python\n", + "lyrics_and_labels = [\n", + " (\"never gonna give you up never gonna let you down\", \"rick\"),\n", + " (\"hello is it me you're looking for\", \"lionel\"),\n", + " (\"cause I'll be rocking this party eight days a week\", \"beastie\"),\n", + "]\n", + "\n", + "def count_words(label, text, d):\n", + " d[label] = len(text.split())\n", + "\n", + "d = dragon.DDict(2, 1, 64 * 1024 * 1024)\n", + "\n", + "procs = [dragon.native.Process(target=count_words, args=(l, t, d)) for t, l in lyrics_and_labels]\n", + "for p in procs:\n", + " p.start()\n", + "for p in procs:\n", + " p.join()\n", + "\n", + "for k, v in d.items():\n", + " print(f\" {k}: {v}\")\n", + "\n", + "d.destroy()\n", + "```\n", + "\n", + "
\n", + "\n", + "**Synchronizing Updates to the Same Key in Parallel** \n", + "\n", + "Because multiple processes may attempt to store an updated value for a key which depends upon the\n", + "existing associated value, care must be taken because whichever process writes last wins. Depending\n", + "upon your code's needs, look at some of the functionality available on the `DDict` that has no\n", + "equivalent on the standard `dict` such as the atomic update `fetch_add` method to add values to\n", + "the existing stored value.\n", + "\n", + "For example, the `fetch_add` will operate atomically to add an integer value to a specified key/value pair. \n", + "\n", + "```python\n", + "def count_words(d, text):\n", + " for word, count in Counter(text.split()).items():\n", + " d.fetch_add(word, count)\n", + "```\n", + "\n", + "Using `fetch_add` to retrieve fetch/added values works in both Python and C++ Dragon APIs.\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "28472c80", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Summary\n", + "\n", + "You used DragonHPC with familiar multiprocessing concepts to launch workers,\n", + "synchronize phases, communicate data, and run data-parallel map operations.\n", + "The same API patterns apply whether you run on one node or many.\n", + "\n", + "| Concept | API |\n", + "|---|---|\n", + "| Start Dragon backend | `mp.set_start_method(\"dragon\")` |\n", + "| Launch process | `mp.Process` and/or `dragon.native.Process(target=..., args=...)` |\n", + "| Wait for completion | `p.join()` |\n", + "| Mutual exclusion | `mp.Lock()` |\n", + "| Shared scalar | `mp.Value(...)` |\n", + "| Message passing | `mp.Queue()` |\n", + "| Phase synchronization | `mp.Barrier(n)` |\n", + "| Pool map | `mp.Pool(...).map(func, data)` |\n", + "| Multi-node placement check | `socket.gethostname()` |\n", + "\n", + "### What next?\n", + "\n", + "Try adapting these exercises to your own application by replacing toy data with\n", + "real workloads and scaling the worker count to your full Dragon allocation." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "168332f4", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "cuPhoton SC26", + "language": "python", + "name": "cuphoton-sc26" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.12" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb new file mode 100644 index 0000000..687c2a0 --- /dev/null +++ b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb @@ -0,0 +1,1619 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "sc26-00", + "metadata": {}, + "source": [ + "# SC26 cuPhoton + DragonHPC Tutorial: From real sky images to GPU workers\n", + "\n", + "**Estimated time:** ~35 minutes \n", + "**Format:** Runnable demos as walkthru of major cuPhoton features and Dragon integration.\n", + "\n", + "A 35-minute walkthrough for the SC26 cuPhoton and Dragon session. We begin with\n", + "observational FITS pixels, add controlled changes, and follow the same data through\n", + "loading, registration, subtraction, candidate fitting, and classification.\n", + "At each distributed stage, compare an ordinary Python calculation with a visible\n", + "`cuphoton` command launched by Dragon. Finish by retaining the complete pipeline\n", + "inside each GPU worker and selecting the newer native CUDA C++ implementations.\n", + "\n", + "| Minutes | Question |\n", + "|---|---|\n", + "| 0–3 | What are the observations, injected signals, and independent work items? |\n", + "| 3–8 | How do FITS loading and WCS registration prepare a pair? |\n", + "| 8–13 | Can several workers subtract the same batch correctly? |\n", + "| 13–19 | What does a candidate fit tell us, and where does it fail? |\n", + "| 19–23 | How do we apply a small trained classifier across GPUs? |\n", + "| 23–31 | What changes when the stages share one persistent GPU worker? |\n", + "| 31–35 | Where do native implementations remove runtime kernel compilation? |\n", + "\n", + "The optional final section adds 5–7 minutes of automatic detection and uncertainty\n", + "analysis. Preparation, downloads, native builds, and training happen **before**\n", + "the session and are not described here. Run cells in order. All computation\n", + "requires Linux, CUDA 13, and the documented Python 3.12 environment.\n" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-01", + "metadata": {}, + "source": [ + "## 1. Choose a prepared workload and launch mode\n", + "\n", + "The background pixels come from real observations. The moving sources, sharp\n", + "artifacts, and labels are controlled injections; this is not a discovery of\n", + "astrophysical transients. The prepared model is trained on those injections and\n", + "is useful for demonstrating the execution path, not survey-ready classification.\n", + "Its held-out results and exact training provenance remain beside the checkpoint.\n", + "\n", + "Set `CUPHOTON_DEMO_ROOT` to the prepared directory and\n", + "`CUPHOTON_DEMO_WORKERS` for your allocation. The executable `%%bash` cells\n", + "use one host (`dragon -s`) by default. Each distributed stage also has complete\n", + "Slurm and SSH commands: replace the single-host command when using a cluster.\n", + "Multinode runs require identical absolute paths for the environment, inputs,\n", + "checkpoint, and outputs on every node.\n", + "\n", + "Python setup exports paths to the shell. The command cells contain the actual\n", + "CLI arguments, followed by Python cells that inspect their results. Each command\n", + "has a 10-minute timeout, a regular-file log, and a GNU `time` wall-clock record.\n", + "The timeout bounds the launcher; after a failure, inspect its owned workers\n", + "before rerunning. The cell shows the command and the last 40 log lines; the complete log remains\n", + "under `RUNS`. Linux Bash, GNU `time` (`/usr/bin/time`), and `timeout` are required." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-02", + "metadata": {}, + "outputs": [], + "source": [ + "# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\n", + "#\n", + "# SPDX-License-Identifier: Apache-2.0\n", + "\n", + "import gc\n", + "import json\n", + "import os\n", + "from pathlib import Path\n", + "import sys\n", + "import time\n", + "import uuid\n", + "\n", + "import numpy as np\n", + "import pandas as pd\n", + "import yaml\n", + "from IPython.display import display\n", + "\n", + "# A served output copy may live elsewhere; point it at the source checkout.\n", + "repo_override = os.environ.get(\"CUPHOTON_DEMO_REPO\", \"/path/to/checkout/repo/cuPhoton\")\n", + "search_roots = ([Path(repo_override).expanduser().resolve()] if repo_override\n", + " else [Path.cwd(), *Path.cwd().parents])\n", + "EXAMPLE = next((\n", + " candidate\n", + " for parent in search_roots\n", + " for candidate in (parent, parent / \"examples\" / \"dragon-imaging-pipeline\")\n", + " if (candidate / \"demo.py\").is_file()\n", + "), None)\n", + "if EXAMPLE is None:\n", + " raise RuntimeError(\n", + " \"Cannot find examples/dragon-imaging-pipeline/demo.py. Start Jupyter from \"\n", + " \"the cuPhoton checkout, or set CUPHOTON_DEMO_REPO to its absolute path.\"\n", + " )\n", + "REPO = EXAMPLE.parent.parent\n", + "sys.path.insert(0, str(EXAMPLE))\n", + "from demo import compare_arrays, image_grid, load_json, summarize_run\n", + "\n", + "DEMO = Path(os.environ.get(\n", + " \"CUPHOTON_DEMO_ROOT\", REPO / \"scratch\" / \"sc26-dragon\"\n", + ")).expanduser().resolve()\n", + "if not (DEMO / \"prepared.json\").is_file():\n", + " raise FileNotFoundError(\n", + " f\"No prepared.json in {DEMO}. Set CUPHOTON_DEMO_ROOT to the completed output \"\n", + " \"of prepare.py; see README.md.\"\n", + " )\n", + "prepared = load_json(DEMO / \"prepared.json\")\n", + "WORKERS = int(os.environ.get(\"CUPHOTON_DEMO_WORKERS\", \"1\"))\n", + "NODES = int(os.environ.get(\"CUPHOTON_DEMO_NODES\", \"2\"))\n", + "HOSTFILE = str(Path(os.environ.get(\n", + " \"CUPHOTON_DEMO_HOSTFILE\", DEMO / \"dragon-hosts.txt\"\n", + ")).expanduser().resolve())\n", + "assert WORKERS > 0 and NODES > 0\n", + "SESSION = f\"notebook-{time.strftime('%Y%m%d-%H%M%S')}-{uuid.uuid4().hex[:6]}\"\n", + "RUNS = DEMO / \"runs\" / SESSION\n", + "RUNS.mkdir(parents=True, exist_ok=False)\n", + "# %%bash inherits these environment variables; PATH selects this kernel's tools.\n", + "os.environ[\"PATH\"] = str(Path(sys.executable).parent) + os.pathsep + os.environ[\"PATH\"]\n", + "os.environ.update({\n", + " \"RUNS\": str(RUNS), \"WORKERS\": str(WORKERS), \"NODES\": str(NODES), \"HOSTFILE\": HOSTFILE,\n", + " \"PAIRS_MANIFEST\": prepared[\"pairs_manifest\"],\n", + " \"PIPELINE_MANIFEST\": prepared[\"pipeline_manifest\"],\n", + " \"NATIVE_PIPELINE_MANIFEST\": prepared[\"native_pipeline_manifest\"],\n", + " \"MODEL_DIR\": prepared[\"model_dir\"], \"DEMO_DATASET\": prepared[\"dataset_dir\"],\n", + " \"XFIT_INPUT\": prepared[\"xfit_input\"], \"XFIT_FEATURES\": prepared[\"xfit_feature_dir\"],\n", + "})\n", + "print({\"data\": str(DEMO), \"runs\": str(RUNS), \"workers\": WORKERS, \"python\": sys.executable})" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-03", + "metadata": {}, + "source": [ + "### Workload manifests and Dragon placement are separate inputs\n", + "\n", + "The YAML below lists **whole aligned image pairs** for xPois. It does not select\n", + "hosts. Dragon selects hosts through `-s`, a Slurm allocation, or a host file;\n", + "cuPhoton binds workers to the available GPUs. xFit and xScan divide their inputs\n", + "into candidate or minibatch chunks. The resident pipeline uses a JSON manifest\n", + "containing a checkpoint, numerical settings, and pairs with candidate positions.\n", + "\n", + "Dragon queues carry control messages and completion metadata. Workers read image\n", + "pixels from shared files. They do not send image arrays through those queues.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-04", + "metadata": {}, + "outputs": [], + "source": [ + "pairs_path = Path(prepared[\"pairs_manifest\"])\n", + "pairs_payload = yaml.safe_load(pairs_path.read_text())\n", + "pairs = pairs_payload[\"pairs\"]\n", + "print(yaml.safe_dump({\"schema\": pairs_payload[\"schema\"], \"pairs\": pairs[:2]},\n", + " sort_keys=False))\n", + "print(f\"{len(pairs)} independent pairs; at most {WORKERS} GPU workers\")\n", + "pipeline_path = Path(prepared[\"pipeline_manifest\"])\n", + "pipeline_payload = load_json(pipeline_path)\n", + "science_settings = pipeline_payload[\"configuration\"]\n", + "xpois_settings = science_settings[\"xpois\"]\n", + "print(\"Pipeline stages:\", \"xPois → xFit → xScan\")\n", + "print(\"Model:\", prepared[\"model_dir\"])\n", + "print(\"Numerical xFit policy:\", science_settings[\"xfit\"].get(\"solver_version\", \"v0.2\"))\n", + "\n", + "# The literal Bash examples below use these published demo settings.\n", + "assert xpois_settings[\"kernel_shape\"] == [15, 15]\n", + "assert xpois_settings[\"basis_sigmas\"] == [1.5] and xpois_settings[\"basis_degrees\"] == [0]\n", + "assert xpois_settings[\"background_degree\"] == 0 and not xpois_settings[\"flux_conserve\"]\n", + "assert science_settings[\"xfit\"][\"max_evaluations\"] == 400\n", + "assert prepared[\"config\"][\"batch_size\"] == 32\n", + "assert prepared[\"config\"][\"inference_split\"] == \"test\"" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-05", + "metadata": {}, + "source": [ + "### Check the numerical environment\n", + "\n", + "Torch is imported before CuPy initializes CUDA. The notebook owns one local GPU\n", + "for the Python comparisons; each Dragon launch starts a fresh coordinator and\n", + "binds its workers before their numerical libraries initialize. Explicit backends\n", + "make a missing GPU or native extension an error instead of silently changing the\n", + "calculation to a CPU run.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-06", + "metadata": {}, + "outputs": [], + "source": [ + "import torch\n", + "import cupy as cp\n", + "import cuphoton\n", + "from astropy.io import fits\n", + "from astropy.wcs import WCS\n", + "\n", + "assert torch.cuda.is_available()\n", + "torch.cuda.set_device(0)\n", + "cp.cuda.Device(0).use()\n", + "print({\"cuPhoton\": cuphoton.__version__, \"Torch\": torch.__version__,\n", + " \"CuPy\": cp.__version__, \"GPU\": torch.cuda.get_device_name(0),\n", + " \"CUDA runtime\": cp.cuda.runtime.runtimeGetVersion()})\n", + "first = pairs[0]\n", + "REFERENCE = Path(first[\"reference\"])\n", + "TARGET = Path(first[\"target\"])\n", + "HDU = int(first.get(\"reference_hdu\", 1))\n", + "data_manifest = load_json(prepared[\"data_manifest\"])\n", + "source_info = data_manifest[\"source\"]\n", + "display(pd.Series({key: source_info[key] for key in (\"title\", \"units\", \"credit\", \"dataset_doi\")}))\n", + "_ = image_grid([fits.getdata(data_manifest[\"crop\"][\"path\"], 1)],\n", + " [\"M51: original archival crop, 3.6 microns\"], columns=1)\n", + "\n", + "assert HDU == int(first.get(\"target_hdu\", 1)) == int(first.get(\"variance_hdu\", 1)) == 1\n", + "os.environ.update({\n", + " \"REFERENCE\": str(REFERENCE), \"TARGET\": str(TARGET),\n", + " \"VARIANCE\": first[\"variance\"], \"FIT_MASK\": first[\"fit_mask\"],\n", + "})" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-07", + "metadata": {}, + "source": [ + "## 2. Read and inspect real FITS pixels · 3–8 minutes\n", + "\n", + "xDR returns device arrays. The receipt below identifies the selected reader and\n", + "HDU; it is not proof of GPUDirect Storage or a hardware decompression engine.\n", + "Display downloads are intentional here. The later resident pipeline keeps its\n", + "large intermediate arrays on the worker GPU.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-08", + "metadata": {}, + "outputs": [], + "source": [ + "from cuphoton.core.fits_io import inspect_fits_images, read_fits_images\n", + "\n", + "planes = inspect_fits_images(REFERENCE)\n", + "display(pd.DataFrame([{\"hdu\": p.hdu, \"shape\": p.shape,\n", + " \"dtype\": str(p.dtype), \"compression\": p.compression}\n", + " for p in planes]))\n", + "reference_read = read_fits_images(REFERENCE, [HDU], reader=\"xdr\", device=True)\n", + "target_read = read_fits_images(TARGET, [HDU], reader=\"xdr\", device=True)\n", + "reference_device = reference_read.arrays[0]\n", + "target_device = target_read.arrays[0]\n", + "reference = cp.asnumpy(reference_device)\n", + "target = cp.asnumpy(target_device)\n", + "print(reference_read.metadata())\n", + "_ = image_grid([reference, target], [\"Observed background + reference injections\",\n", + " \"Controlled later scene\"],\n", + " columns=2, shared_scale=True)\n" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-09", + "metadata": {}, + "source": [ + "### Register onto an explicit reference WCS\n", + "\n", + "The preparation step also saves a shifted copy of the first target with a\n", + "corresponding WCS. xRep uses the WCS to return it to the reference pixel grid.\n", + "The aligned pair used below for subtraction was prepared in advance so every\n", + "worker reads the same immutable bytes.\n", + "\n", + "FITS loading and xRep are local operations in this walkthrough. xRep has a normal\n", + "CLI, but no `--executor dragon`; we do not manufacture a distributed equivalent.\n", + "Once registration is complete, Dragon distributes complete independent pairs.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-10", + "metadata": {}, + "outputs": [], + "source": [ + "from cuphoton.xrep import BBox, Grid, build_stack_spec_from_fits, reproject_stack\n", + "\n", + "reprojection = data_manifest[\"reprojection\"]\n", + "RAW_TARGET = Path(reprojection[\"raw_target\"])\n", + "target_wcs = WCS(fits.getheader(REFERENCE, HDU), naxis=2)\n", + "height, width = reference.shape\n", + "sources, stack_spec = build_stack_spec_from_fits(\n", + " [REFERENCE, RAW_TARGET], hdu=HDU,\n", + " grid=Grid.from_wcs(target_wcs), output_bbox=BBox(0, 0, width, height),\n", + " interpolation=\"lanczos3\", mapping_grid_step=1,\n", + " fits_reader=\"xdr\", device=True,\n", + ")\n", + "aligned = reproject_stack(sources, stack_spec, backend=\"cupy\")\n", + "raw_target = fits.getdata(RAW_TARGET, HDU)\n", + "_ = image_grid([raw_target, aligned.images[1], target],\n", + " [\"Shifted detector pixels\", \"xRep: reference grid\", \"Prepared aligned target\"],\n", + " shared_scale=True)\n", + "\n", + "os.environ[\"RAW_TARGET\"] = str(RAW_TARGET)\n", + "# A local view makes the known three-pixel shift visible at notebook scale.\n", + "anchor = data_manifest[\"pairs\"][0][\"candidates\"][0]\n", + "x, y = int(anchor[\"x\"]), int(anchor[\"y\"])\n", + "view = np.s_[y - 25:y + 26, x - 25:x + 26]\n", + "_ = image_grid([raw_target[view], aligned.images[1][view],\n", + " (raw_target - aligned.images[1])[view]],\n", + " [\"Before WCS registration: 51 px\", \"After WCS registration: 51 px\",\n", + " \"Before minus after: own scale\"], diverging=[False, False, True])" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-11", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xrep-cupy.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xrep-cupy.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " cuphoton xrep reproject-stack \\\n", + " --inputs \"$REFERENCE,$RAW_TARGET\" --hdu 1 \\\n", + " --target-wcs \"$REFERENCE\" --target-hdu 1 \\\n", + " --backend cupy --fits-reader xdr --interpolation lanczos3 \\\n", + " --mapping-grid-step 1 --write-fits \\\n", + " --output-dir \"$RUNS\" --name xrep-cupy >\"$RUNS/xrep-cupy.log\" 2>&1" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-12", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"xrep-cupy: launcher-to-exit seconds:\", float((RUNS / \"xrep-cupy.elapsed\").read_text()))\n", + "cli_aligned = np.load(RUNS / \"xrep-cupy\" / \"artifacts\" / \"reprojected_stack.npy\")\n", + "print(compare_arrays(aligned.images, cli_aligned, label=\"xRep Python / CLI\"))" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-13", + "metadata": {}, + "source": [ + "## 3. Match the PSF and subtract · 8–13 minutes\n", + "\n", + "Fit a kernel and differential background so the reference resembles the target,\n", + "then form **target − matched reference**. The injected changing sources are\n", + "excluded by the prepared fit mask. The basis widths are inputs, not parameters\n", + "optimized by this solve. Both routes use the same basis, mask and variance.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-14", + "metadata": {}, + "outputs": [], + "source": [ + "from cuphoton.xpois import GaussianBasisComponent, solve_constant_kernel_device\n", + "\n", + "components = [GaussianBasisComponent(sigma=s, degree=d)\n", + " for s, d in zip(xpois_settings[\"basis_sigmas\"],\n", + " xpois_settings[\"basis_degrees\"], strict=True)]\n", + "variance = fits.getdata(first[\"variance\"], int(first.get(\"variance_hdu\", 1)))\n", + "fit_mask_path = Path(first[\"fit_mask\"])\n", + "fit_mask = (np.load(fit_mask_path, allow_pickle=False) if fit_mask_path.suffix == \".npy\"\n", + " else fits.getdata(fit_mask_path, 1)).astype(bool)\n", + "solve_options = dict(\n", + " kernel_shape=tuple(xpois_settings[\"kernel_shape\"]),\n", + " variance=cp.asarray(variance), fit_mask=cp.asarray(fit_mask),\n", + " background_degree=xpois_settings[\"background_degree\"],\n", + " flux_conserve=xpois_settings[\"flux_conserve\"],\n", + ")\n", + "subtraction = solve_constant_kernel_device(\n", + " reference_device, target_device, components, backend=\"cupy\", **solve_options\n", + ")\n", + "difference = cp.asnumpy(subtraction.residual)\n", + "print({\"backend\": subtraction.backend, \"fit_pixels\": int(subtraction.fit_pixel_count),\n", + " \"chi2\": float(subtraction.chi2), \"kernel_sum\": float(subtraction.kernel.sum())})\n", + "_ = image_grid([reference, target, cp.asnumpy(subtraction.matched)],\n", + " [\"Reference\", \"Target\", \"Matched reference\"], shared_scale=True)\n", + "_ = image_grid([cp.asnumpy(subtraction.kernel), difference, fit_mask],\n", + " [\"Fitted kernel\", \"Difference: target − matched\", \"Kernel-fit pixels\"],\n", + " diverging=[False, True, False])\n" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-15", + "metadata": {}, + "source": [ + "### Run the same subtraction over the image-pair batch with Dragon\n", + "\n", + "One pair is one item; one GPU worker can process several items. Increasing the\n", + "number of candidates within a single pair does not create more xPois workers.\n", + "The single-host cell and the cluster alternatives use the same numerical arguments." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-16", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xpois-dragon.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xpois-dragon.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " dragon -s -t tcp -o tcp cuphoton xpois fit-batch \\\n", + " --executor dragon --backend cupy --manifest \"$PAIRS_MANIFEST\" --fits-reader xdr \\\n", + " --kernel-height 15 --kernel-width 15 --basis-sigmas 1.5 --basis-degrees 0 \\\n", + " --background-degree 0 --output-dir \"$RUNS\" --name xpois-dragon \\\n", + " --max-workers \"$WORKERS\" >\"$RUNS/xpois-dragon.log\" 2>&1" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-17", + "metadata": {}, + "source": [ + "For an allocated cluster, replace the `dragon -s ...` command above with\n", + "one of these complete commands; retain the Bash cell's timing and log redirection.\n", + "Shared absolute paths must exist on every host.\n", + "\n", + "```bash\n", + "# Slurm: run inside an interactive allocation.\n", + "dragon --wlm slurm --nodes \"$NODES\" -t tcp -o tcp cuphoton xpois fit-batch \\\n", + " --executor dragon --backend cupy --manifest \"$PAIRS_MANIFEST\" --fits-reader xdr \\\n", + " --kernel-height 15 --kernel-width 15 --basis-sigmas 1.5 --basis-degrees 0 \\\n", + " --background-degree 0 --output-dir \"$RUNS\" --name xpois-dragon \\\n", + " --max-workers \"$WORKERS\"\n", + "\n", + "# SSH: use the host file for dedicated, authorized hosts.\n", + "dragon --wlm ssh --nodes \"$NODES\" --hostfile \"$HOSTFILE\" -t tcp -o tcp cuphoton xpois fit-batch \\\n", + " --executor dragon --backend cupy --manifest \"$PAIRS_MANIFEST\" --fits-reader xdr \\\n", + " --kernel-height 15 --kernel-width 15 --basis-sigmas 1.5 --basis-degrees 0 \\\n", + " --background-degree 0 --output-dir \"$RUNS\" --name xpois-dragon \\\n", + " --max-workers \"$WORKERS\"\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-18", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"xpois-dragon: launcher-to-exit seconds:\", float((RUNS / \"xpois-dragon.elapsed\").read_text()))\n", + "_ = summarize_run(RUNS / \"xpois-dragon\")\n", + "cli_difference = np.load(RUNS / \"xpois-dragon\" / \"items\" / first[\"id\"] /\n", + " \"artifacts\" / \"residual.npy\")\n", + "print(compare_arrays(difference, cli_difference, label=\"xPois Python / Dragon\"))\n", + "_ = image_grid([difference, cli_difference, difference - cli_difference],\n", + " [\"Python difference\", \"Dragon difference\", \"Numerical difference\"],\n", + " diverging=True)" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-19", + "metadata": {}, + "source": [ + "## 4. Fit candidate stamps · 13–19 minutes\n", + "\n", + "The prepared candidates contain known injections and controls; this section is\n", + "not a source detector. Each input stamp and candidate ID is frozen in an NPZ\n", + "file derived from the same subtraction settings. Both routes derive the same\n", + "initial guesses from those stamps. A Gaussian dipole models\n", + "a positive and a negative lobe. A sharp artifact, blank stamp, or single brightening\n", + "source can violate that model even when the optimizer returns parameters.\n", + "\n", + "Keep **solver policy v0.2**, float64, and candidate chunk size identical in the\n", + "Python and Dragon runs. Inspect convergence and uncertainty validity separately.\n", + "The final optional chain adds detection, quality flags, and single-source refits.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-20", + "metadata": {}, + "outputs": [], + "source": [ + "from cuphoton.xfit import GaussianDipoleModel, LMConfig, fit_dipoles\n", + "from cuphoton.xfit.io import load_xfit_dataset\n", + "\n", + "xfit_data = load_xfit_dataset(prepared[\"xfit_input\"], model=\"gaussian\", mode=\"difference\")\n", + "CHUNK = int(prepared.get(\"config\", {}).get(\"chunk_size\", 32))\n", + "MAX_EVALUATIONS = int(science_settings[\"xfit\"][\"max_evaluations\"])\n", + "assert CHUNK == 32 and MAX_EVALUATIONS == 400\n", + "fit_config = LMConfig(solver_version=\"v0.2\", max_evaluations=MAX_EVALUATIONS)\n", + "python_fits = [\n", + " fit_dipoles(\n", + " xfit_data.images[start:start + CHUNK], model=\"gaussian\", mode=\"difference\",\n", + " initial=None if xfit_data.initial is None else xfit_data.initial[start:start + CHUNK],\n", + " backend=\"cupy\", config=fit_config,\n", + " )\n", + " for start in range(0, xfit_data.batch_size, CHUNK)\n", + "]\n", + "python_parameters = np.concatenate([result.parameters for result in python_fits])\n", + "python_converged = np.concatenate([result.converged for result in python_fits])\n", + "python_valid = np.concatenate([result.uncertainty_valid for result in python_fits])\n", + "print({\"candidates\": xfit_data.batch_size, \"converged\": int(python_converged.sum()),\n", + " \"valid_covariance\": int(python_valid.sum()), \"solver_policy\": \"v0.2\"})\n", + "model = GaussianDipoleModel(xfit_data.images.shape[-2:], dtype=np.float64)\n", + "fit_model = np.asarray(model.evaluate(python_fits[0].parameters, mode=\"difference\"))\n", + "_ = image_grid([xfit_data.images[0], fit_model[0]],\n", + " [\"Difference stamp\", \"Gaussian dipole model\"],\n", + " columns=2, diverging=True, shared_scale=True)\n", + "fit_residual = -python_fits[0].residuals[0] # xFit returns model minus data.\n", + "stamp_peak = float(np.max(np.abs(xfit_data.images[0])))\n", + "residual_peak = float(np.max(np.abs(fit_residual)))\n", + "print({\"residual_peak_image_units\": residual_peak,\n", + " \"residual_peak_over_stamp_peak\": residual_peak / max(stamp_peak, 1e-30)})\n", + "_ = image_grid([fit_residual],\n", + " [f\"Data − model; own scale; peak/stamp = {residual_peak / max(stamp_peak, 1e-30):.2%}\"],\n", + " columns=1, diverging=True)" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-21", + "metadata": {}, + "source": [ + "### Recover the known motion, then compare executors\n", + "\n", + "The stamp and model share a color range. The residual has its own labeled range\n", + "so a good fit's remaining structure stays visible; saturated residual colors do\n", + "not mean errors as large as the source.\n", + "\n", + "The injected old and new centers supply an independent recovery check. xFit\n", + "positions are relative to the center of each odd-sized stamp. Add the candidate's\n", + "full-image `(x, y)` before comparing the positive lobe to the new position and the\n", + "negative lobe to the old position. These errors are in **pixels**. We report every\n", + "injected mover, including failed fits; backend agreement alone would not show\n", + "whether either calculation recovered the signal. Circular lobes can leave\n", + "orientation poorly constrained, so inspect center error separately from the\n", + "full covariance's validity flag.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-22", + "metadata": {}, + "outputs": [], + "source": [ + "truth_by_id = {candidate[\"candidate_id\"]: candidate\n", + " for item in data_manifest[\"pairs\"] for candidate in item[\"candidates\"]}\n", + "recovery_rows = []\n", + "for index, candidate_id in enumerate(xfit_data.candidate_id):\n", + " candidate = truth_by_id[str(candidate_id)]\n", + " if candidate[\"kind\"] != \"moving_source\":\n", + " continue\n", + " origin = np.array([candidate[\"x\"], candidate[\"y\"]], dtype=float)\n", + " fitted_new = python_parameters[index, 4:6] + origin\n", + " fitted_old = python_parameters[index, 6:8] + origin\n", + " true_new = np.array(candidate[\"truth\"][\"target_xy\"])\n", + " true_old = np.array(candidate[\"truth\"][\"reference_xy\"])\n", + " recovery_rows.append({\n", + " \"candidate_id\": str(candidate_id),\n", + " \"positive_center_error_px\": float(np.linalg.norm(fitted_new - true_new)),\n", + " \"negative_center_error_px\": float(np.linalg.norm(fitted_old - true_old)),\n", + " \"motion_vector_error_px\": float(np.linalg.norm((fitted_new - fitted_old) - (true_new - true_old))),\n", + " \"converged\": bool(python_converged[index]),\n", + " \"uncertainty_valid\": bool(python_valid[index]),\n", + " })\n", + "recovery = pd.DataFrame(recovery_rows)\n", + "display(recovery.head(12))\n", + "error_columns = [\"positive_center_error_px\", \"negative_center_error_px\", \"motion_vector_error_px\"]\n", + "display(recovery[error_columns].describe(percentiles=[0.5, 0.9]))\n", + "# A small histogram table includes failed fits rather than filtering them away.\n", + "bins = [0, 0.1, 0.25, 0.5, 1, 2, np.inf]\n", + "histogram = {\"error_px\": [\"0–0.1\", \"0.1–0.25\", \"0.25–0.5\", \"0.5–1\", \"1–2\", \"2+\"]}\n", + "for column in error_columns:\n", + " histogram[column] = np.histogram(recovery[column], bins=bins)[0]\n", + "display(pd.DataFrame(histogram))\n", + "print({\"moving_sources\": len(recovery), \"converged\": int(recovery.converged.sum()),\n", + " \"valid_covariance\": int(recovery.uncertainty_valid.sum()),\n", + " \"nonfinite_error_rows\": int((~np.isfinite(recovery[error_columns])).any(axis=1).sum())})\n", + "recovery.to_csv(RUNS / \"injection-recovery.csv\", index=False)\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-23", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xfit-dragon.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xfit-dragon.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " dragon -s -t tcp -o tcp cuphoton xfit fit-dipoles \\\n", + " --executor dragon --input \"$XFIT_INPUT\" --model gaussian --mode difference \\\n", + " --backend cupy --compute-dtype float64 --solver-version v0.2 \\\n", + " --chunk-size 32 --max-evaluations 400 \\\n", + " --output-dir \"$RUNS/xfit-dragon\" --max-workers \"$WORKERS\" >\"$RUNS/xfit-dragon.log\" 2>&1" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-24", + "metadata": {}, + "source": [ + "For an allocated cluster, replace the `dragon -s ...` command above with\n", + "one of these complete commands; retain the Bash cell's timing and log redirection.\n", + "Shared absolute paths must exist on every host.\n", + "\n", + "```bash\n", + "# Slurm: run inside an interactive allocation.\n", + "dragon --wlm slurm --nodes \"$NODES\" -t tcp -o tcp cuphoton xfit fit-dipoles \\\n", + " --executor dragon --input \"$XFIT_INPUT\" --model gaussian --mode difference \\\n", + " --backend cupy --compute-dtype float64 --solver-version v0.2 \\\n", + " --chunk-size 32 --max-evaluations 400 \\\n", + " --output-dir \"$RUNS/xfit-dragon\" --max-workers \"$WORKERS\"\n", + "\n", + "# SSH: use the host file for dedicated, authorized hosts.\n", + "dragon --wlm ssh --nodes \"$NODES\" --hostfile \"$HOSTFILE\" -t tcp -o tcp cuphoton xfit fit-dipoles \\\n", + " --executor dragon --input \"$XFIT_INPUT\" --model gaussian --mode difference \\\n", + " --backend cupy --compute-dtype float64 --solver-version v0.2 \\\n", + " --chunk-size 32 --max-evaluations 400 \\\n", + " --output-dir \"$RUNS/xfit-dragon\" --max-workers \"$WORKERS\"\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-25", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"xfit-dragon: launcher-to-exit seconds:\", float((RUNS / \"xfit-dragon.elapsed\").read_text()))\n", + "fit_table = pd.read_parquet(RUNS / \"xfit-dragon\" / \"scientific\" / \"fits.parquet\")\n", + "assert fit_table[\"candidate_id\"].tolist() == xfit_data.candidate_id.tolist()\n", + "print(compare_arrays(python_parameters,\n", + " fit_table[list(python_fits[0].parameter_names)].to_numpy(),\n", + " label=\"xFit Python / Dragon parameters\"))\n", + "np.testing.assert_array_equal(python_converged, fit_table[\"converged\"].to_numpy())\n", + "display(fit_table[[\"candidate_id\", \"converged\", \"uncertainty_valid\"]].head(8))\n", + "_ = summarize_run(RUNS / \"xfit-dragon\")" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-26", + "metadata": {}, + "source": [ + "## 5. Score the candidate batch · 19–23 minutes\n", + "\n", + "The small triplet-plus-xFit model was trained in preparation, with disjoint\n", + "training, validation and held-out inputs. The table below reports that particular\n", + "injection experiment. Training runs 20 GPU epochs and retains the checkpoint\n", + "with the best validation ROC AUC; the qualified run retained **epoch 1**. The\n", + "history below shows the later overfitting. Scores are uncalibrated and narrowly\n", + "clustered near 0.5; inspect their ranking and logits as well as the validation\n", + "threshold. They are not probabilities that an arbitrary sky source is real.\n", + "\n", + "The Python and CLI treatments load the same checkpoint and feature schema, and\n", + "preserve the same inference minibatches. The stock dataset inference API is used\n", + "here so both treatments use the same host sigmoid and sample ordering." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-27", + "metadata": {}, + "outputs": [], + "source": [ + "from cuphoton.xscan.dataset import StampDataset\n", + "from cuphoton.xscan.training import load_model_from_checkpoint, predict_dataset\n", + "\n", + "training_summary = load_json(Path(prepared[\"model_dir\"]) / \"summary.json\")\n", + "training_history = pd.DataFrame(load_json(Path(prepared[\"model_dir\"]) / \"history.json\"))\n", + "best_epoch = int(training_summary[\"early_stopping\"][\"best_epoch\"])\n", + "print({\"epochs_completed\": training_summary[\"epochs_completed\"],\n", + " \"retained_best_epoch\": best_epoch, \"selection_metric\": training_summary[\"best_metric\"]})\n", + "# The beginning, best epoch, and end show the training trend without a long table.\n", + "history_rows = training_history[\"epoch\"].isin([1, 2, 3, best_epoch, 10, 20])\n", + "display(training_history.loc[history_rows, [\"epoch\", \"train_loss\", \"val_loss\", \"val_roc_auc\"]])\n", + "\n", + "metrics = prepared[\"metrics\"]\n", + "if isinstance(metrics, str):\n", + " metrics = load_json(metrics)\n", + "metric_columns = [\"sample_count\", \"balanced_accuracy\", \"roc_auc\", \"precision\", \"recall\", \"fp\", \"fn\"]\n", + "display(pd.DataFrame(metrics[\"splits\"]).T.loc[[\"val\", \"test\"], metric_columns])\n", + "print(\"Threshold selected on validation:\", metrics[\"decision_threshold\"])\n", + "BATCH = int(prepared.get(\"config\", {}).get(\"batch_size\", 32))\n", + "SPLIT = prepared.get(\"config\", {}).get(\"inference_split\", \"all\")\n", + "assert BATCH == 32 and SPLIT == \"test\"\n", + "classifier, checkpoint, performance = load_model_from_checkpoint(\n", + " Path(prepared[\"model_dir\"]), device=torch.device(\"cuda:0\")\n", + ")\n", + "dataset = StampDataset(\n", + " Path(prepared[\"dataset_dir\"]), input_mode=\"triplet\", split=SPLIT,\n", + " xfit_feature_dir=Path(prepared[\"xfit_feature_dir\"]),\n", + " xfit_feature_names=tuple(classifier.xfit_feature_names),\n", + ")\n", + "python_predictions = predict_dataset(\n", + " model=classifier, dataset=dataset, batch_size=BATCH,\n", + " device=torch.device(\"cuda:0\"), performance=performance,\n", + ")\n", + "# Fixed first two examples of each injected class, independent of model score.\n", + "prediction_rows = python_predictions[\"metadata_rows\"]\n", + "contact_positions = [\n", + " position\n", + " for kind in (\"moving_source\", \"detector_artifact\", \"unchanged_control\")\n", + " for position in [i for i, row in enumerate(prediction_rows) if row[\"kind\"] == kind][:2]\n", + "]\n", + "contact_samples = [int(dataset.indices[position]) for position in contact_positions]\n", + "_ = image_grid([dataset.difference[sample] for sample in contact_samples],\n", + " [prediction_rows[position][\"kind\"] + chr(10) + prediction_rows[position][\"candidate_id\"]\n", + " for position in contact_positions], diverging=True)\n", + "# Rank 1 is the highest score across the entire demonstration candidate batch.\n", + "score_ranks = pd.Series(python_predictions[\"probabilities\"]).rank(method=\"min\", ascending=False)\n", + "print({\"uncalibrated_score_min\": float(np.min(python_predictions[\"probabilities\"])),\n", + " \"uncalibrated_score_max\": float(np.max(python_predictions[\"probabilities\"]))})\n", + "# Truth is known from injection; scores, ranks and decisions come from the model.\n", + "threshold = float(metrics[\"decision_threshold\"])\n", + "display(pd.DataFrame([\n", + " {\"candidate_id\": prediction_rows[position][\"candidate_id\"],\n", + " \"injected_kind\": prediction_rows[position][\"kind\"],\n", + " \"injected_label\": int(python_predictions[\"labels\"][position]),\n", + " \"model_logit\": float(python_predictions[\"logits\"][position]),\n", + " \"score_rank\": int(score_ranks.iloc[position]),\n", + " \"uncalibrated_score\": float(python_predictions[\"probabilities\"][position]),\n", + " \"model_decision\": bool(python_predictions[\"probabilities\"][position] >= threshold)}\n", + " for position in contact_positions\n", + "]))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-28", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xscan-dragon.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xscan-dragon.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " dragon -s -t tcp -o tcp cuphoton xscan infer-real-bogus \\\n", + " --executor dragon --run-dir \"$MODEL_DIR\" --dataset-dir \"$DEMO_DATASET\" \\\n", + " --split test --batch-size 32 --num-workers 0 --task-batches 1 \\\n", + " --use-xfit-features --xfit-feature-dir \"$XFIT_FEATURES\" \\\n", + " --output-dir \"$RUNS/xscan-dragon\" --max-workers \"$WORKERS\" >\"$RUNS/xscan-dragon.log\" 2>&1" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-29", + "metadata": {}, + "source": [ + "For an allocated cluster, replace the `dragon -s ...` command above with\n", + "one of these complete commands; retain the Bash cell's timing and log redirection.\n", + "Shared absolute paths must exist on every host.\n", + "\n", + "```bash\n", + "# Slurm: run inside an interactive allocation.\n", + "dragon --wlm slurm --nodes \"$NODES\" -t tcp -o tcp cuphoton xscan infer-real-bogus \\\n", + " --executor dragon --run-dir \"$MODEL_DIR\" --dataset-dir \"$DEMO_DATASET\" \\\n", + " --split test --batch-size 32 --num-workers 0 --task-batches 1 \\\n", + " --use-xfit-features --xfit-feature-dir \"$XFIT_FEATURES\" \\\n", + " --output-dir \"$RUNS/xscan-dragon\" --max-workers \"$WORKERS\"\n", + "\n", + "# SSH: use the host file for dedicated, authorized hosts.\n", + "dragon --wlm ssh --nodes \"$NODES\" --hostfile \"$HOSTFILE\" -t tcp -o tcp cuphoton xscan infer-real-bogus \\\n", + " --executor dragon --run-dir \"$MODEL_DIR\" --dataset-dir \"$DEMO_DATASET\" \\\n", + " --split test --batch-size 32 --num-workers 0 --task-batches 1 \\\n", + " --use-xfit-features --xfit-feature-dir \"$XFIT_FEATURES\" \\\n", + " --output-dir \"$RUNS/xscan-dragon\" --max-workers \"$WORKERS\"\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-30", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"xscan-dragon: launcher-to-exit seconds:\", float((RUNS / \"xscan-dragon.elapsed\").read_text()))\n", + "scientific = RUNS / \"xscan-dragon\" / \"scientific\"\n", + "np.testing.assert_array_equal(dataset.indices, np.load(scientific / \"sample_index.npy\"))\n", + "print(compare_arrays(python_predictions[\"logits\"], np.load(scientific / \"logits.npy\"),\n", + " label=\"xScan Python / Dragon logits\"))\n", + "print(compare_arrays(python_predictions[\"probabilities\"],\n", + " np.load(scientific / \"probabilities.npy\"),\n", + " label=\"xScan Python / Dragon probabilities\"))\n", + "_ = summarize_run(RUNS / \"xscan-dragon\")" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-31", + "metadata": {}, + "source": [ + "## 6. Keep the whole pipeline in one worker · 23–31 minutes\n", + "\n", + "The separate commands above make stage boundaries inspectable. The resident\n", + "pipeline processes an entire pair through xPois → xFit → feature conversion →\n", + "xScan in one worker, reusing the model and CUDA context. CuPy and Torch share\n", + "compatible device buffers via DLPack. It writes compact results instead of full\n", + "intermediate images.\n", + "\n", + "This pipeline takes already aligned pairs and supplied candidate coordinates.\n", + "It does not perform xRep or detection, and its xFit feature contract is unmasked,\n", + "unweighted Gaussian fitting. Its xPois variance and mask do not become xFit\n", + "weights. The optional survey chain below has a different, richer contract.\n", + "\n", + "Preparation fits each full corpus in one local xFit call. The live xFit comparison\n", + "uses 32-candidate chunks, and the resident pipeline refits each 32-candidate pair.\n", + "Poorly constrained artifact fits can vary with batch size. Standalone inference\n", + "uses the saved feature bundle, so its scores are a separate comparison from\n", + "resident feature recomputation.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-32", + "metadata": {}, + "outputs": [], + "source": [ + "from cuphoton.xscan.device_pipeline import (\n", + " DeviceWorkerContext, decode_device_pipeline_evidence, run_device_pipeline_item,\n", + ")\n", + "from cuphoton.xscan.pipeline_executor import load_pipeline_manifest\n", + "\n", + "pipeline_config, pipeline_items = load_pipeline_manifest(pipeline_path)\n", + "context = DeviceWorkerContext.initialize(pipeline_config)\n", + "try:\n", + " # Readable API example: one pair. Full-corpus timings use the CLI below.\n", + " started = time.perf_counter()\n", + " api_result = run_device_pipeline_item(pipeline_items[0], context)\n", + " api_item_seconds = time.perf_counter() - started\n", + "finally:\n", + " context.producer_stream.synchronize()\n", + " context.consumer_stream.synchronize()\n", + "print({\"context_setup_sec\": context.load_seconds, \"one_item_sec\": api_item_seconds})\n", + "display(pd.json_normalize(api_result.transfers.to_payload()))\n", + "# Release the local model before launching fresh workers on the same GPU.\n", + "del context, classifier\n", + "cp.get_default_memory_pool().free_all_blocks()\n", + "torch.cuda.empty_cache()\n", + "gc.collect()\n" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-33", + "metadata": {}, + "source": [ + "### Run the full corpus locally, then with Dragon\n", + "\n", + "The local command is `cuphoton xscan run-pipeline --executor processes`. It uses\n", + "one persistent process on one explicitly visible GPU. Both CLI treatments run\n", + "all prepared pairs with one warmup and three measured rounds; the earlier Python\n", + "cell runs one representative pair solely to expose the API and data flow.\n", + "\n", + "The local child uses the first GPU already visible to the notebook, preserving\n", + "an inherited scheduler mask. Dragon can use the configured worker count across\n", + "its selected hosts. This compares execution arrangements for the same corpus;\n", + "keep worker count and device differences visible alongside timing results.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-34", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "# Use the notebook's first visible GPU, preserving an inherited scheduler mask.\n", + "export CUDA_VISIBLE_DEVICES=\"${CUDA_VISIBLE_DEVICES:-0}\"\n", + "export CUDA_VISIBLE_DEVICES=\"${CUDA_VISIBLE_DEVICES%%,*}\"\n", + "trap 'tail -n 40 \"$RUNS/pipeline-local.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/pipeline-local.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " cuphoton xscan run-pipeline \\\n", + " --executor processes --workers-per-gpu 1 --manifest \"$PIPELINE_MANIFEST\" \\\n", + " --output-dir \"$RUNS\" --name pipeline-local --warmup-rounds 1 --measure-rounds 3 >\"$RUNS/pipeline-local.log\" 2>&1" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-35", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"pipeline-local: launcher-to-exit seconds:\", float((RUNS / \"pipeline-local.elapsed\").read_text()))\n", + "_ = summarize_run(RUNS / \"pipeline-local\")\n", + "local_rounds = sorted((RUNS / \"pipeline-local\" / \"rounds\").glob(\"measure-*\"))\n", + "assert len(local_rounds) == 3\n", + "local_by_id = {\n", + " item.item_id: load_json(local_rounds[-1] / \"items\" / item.item_id / \"summary.json\")\n", + " for item in pipeline_items\n", + "}\n", + "api_arrays = decode_device_pipeline_evidence(api_result.scientific_evidence, config=pipeline_config)\n", + "cli_arrays = decode_device_pipeline_evidence(\n", + " local_by_id[api_result.item_id][\"scientific_evidence\"], config=pipeline_config,\n", + ")\n", + "for name in api_arrays:\n", + " compare_arrays(api_arrays[name], cli_arrays[name], rtol=1e-8, atol=1e-10,\n", + " label=f\"Direct API / local CLI: {name}\")\n", + "\n", + "print(f\"Direct API / local CLI: {len(api_arrays)} scientific arrays passed\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-36", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/pipeline-dragon.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/pipeline-dragon.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " dragon -s -t tcp -o tcp cuphoton xscan run-pipeline \\\n", + " --executor dragon --manifest \"$PIPELINE_MANIFEST\" \\\n", + " --output-dir \"$RUNS\" --name pipeline-dragon \\\n", + " --warmup-rounds 1 --measure-rounds 3 --max-workers \"$WORKERS\" >\"$RUNS/pipeline-dragon.log\" 2>&1" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-37", + "metadata": {}, + "source": [ + "For an allocated cluster, replace the `dragon -s ...` command above with\n", + "one of these complete commands; retain the Bash cell's timing and log redirection.\n", + "Shared absolute paths must exist on every host.\n", + "\n", + "```bash\n", + "# Slurm: run inside an interactive allocation.\n", + "dragon --wlm slurm --nodes \"$NODES\" -t tcp -o tcp cuphoton xscan run-pipeline \\\n", + " --executor dragon --manifest \"$PIPELINE_MANIFEST\" \\\n", + " --output-dir \"$RUNS\" --name pipeline-dragon \\\n", + " --warmup-rounds 1 --measure-rounds 3 --max-workers \"$WORKERS\"\n", + "\n", + "# SSH: use the host file for dedicated, authorized hosts.\n", + "dragon --wlm ssh --nodes \"$NODES\" --hostfile \"$HOSTFILE\" -t tcp -o tcp cuphoton xscan run-pipeline \\\n", + " --executor dragon --manifest \"$PIPELINE_MANIFEST\" \\\n", + " --output-dir \"$RUNS\" --name pipeline-dragon \\\n", + " --warmup-rounds 1 --measure-rounds 3 --max-workers \"$WORKERS\"\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-38", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"pipeline-dragon: launcher-to-exit seconds:\", float((RUNS / \"pipeline-dragon.elapsed\").read_text()))\n", + "_ = summarize_run(RUNS / \"pipeline-dragon\")" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-39", + "metadata": {}, + "source": [ + "### Verify the science and explain the timers\n", + "\n", + "Compare the compact scientific evidence for every item, rather than accepting\n", + "only a successful launcher exit. The root execution summary also verifies worker\n", + "placement, output records and shutdown. Small images can spend more time in\n", + "launch and I/O than in arithmetic; the notebook does not promise a speedup.\n", + "\n", + "The one-item Python illustration excludes process startup and result-file\n", + "publication. Use the full-corpus CLI runs for timing comparisons. Their batch\n", + "timers include dispatch, input reads, computation and worker outputs;\n", + "validation/merging follows. Show those boundaries and actual worker counts\n", + "alongside launcher-to-exit time. Do not divide unmatched timers to claim\n", + "acceleration.\n", + "\n", + "GNU `time` writes each complete command's elapsed seconds to `.elapsed`;\n", + "stdout/stderr go to `.log`. The Python cell reads that timing separately\n", + "from the worker and batch timers reported by cuPhoton. The final local round is\n", + "the baseline; skip its eight self-comparisons, leaving 40 item-round comparisons." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-40", + "metadata": {}, + "outputs": [], + "source": [ + "parity = []\n", + "for treatment in (\"pipeline-local\", \"pipeline-dragon\"):\n", + " round_dirs = sorted((RUNS / treatment / \"rounds\").glob(\"measure-*\"))\n", + " assert len(round_dirs) == 3\n", + " for round_dir in round_dirs:\n", + " if treatment == \"pipeline-local\" and round_dir == local_rounds[-1]:\n", + " continue # This is the reference round, not an independent comparison.\n", + " for item in pipeline_items:\n", + " observed_payload = load_json(round_dir / \"items\" / item.item_id / \"summary.json\")\n", + " local = local_by_id[item.item_id]\n", + " assert observed_payload[\"item_id\"] == local[\"item_id\"]\n", + " expected = decode_device_pipeline_evidence(local[\"scientific_evidence\"],\n", + " config=pipeline_config)\n", + " observed = decode_device_pipeline_evidence(observed_payload[\"scientific_evidence\"],\n", + " config=pipeline_config)\n", + " for name in expected:\n", + " compare_arrays(expected[name], observed[name], rtol=1e-8, atol=1e-10,\n", + " label=f\"{item.item_id}: {name}\")\n", + " parity.append({\"treatment\": treatment, \"round\": round_dir.name,\n", + " \"item\": item.item_id, \"arrays_checked\": len(expected), \"parity\": \"passed\"})\n", + "display(pd.DataFrame(parity))\n", + "(RUNS / \"pipeline-parity.json\").write_text(json.dumps(parity, indent=2) + chr(10))" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-41", + "metadata": {}, + "source": [ + "### Saved features versus features recomputed by the resident pipeline\n", + "\n", + "This is a diagnostic across the two feature-generation batch shapes described\n", + "above, separate from the executor-parity checks. Report score differences and\n", + "decision flips without requiring the two feature bundles to be identical." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-42", + "metadata": {}, + "outputs": [], + "source": [ + "resident_scores = {}\n", + "for item in pipeline_items:\n", + " arrays = decode_device_pipeline_evidence(\n", + " local_by_id[item.item_id][\"scientific_evidence\"], config=pipeline_config,\n", + " )\n", + " for candidate, score in zip(item.candidates, arrays[\"xscan.probabilities\"], strict=True):\n", + " resident_scores[str(candidate.candidate_id)] = float(score)\n", + "score_comparison = pd.DataFrame({\n", + " \"candidate_id\": [row[\"candidate_id\"] for row in prediction_rows],\n", + " \"kind\": [row[\"kind\"] for row in prediction_rows],\n", + " \"saved_feature_score\": python_predictions[\"probabilities\"],\n", + " \"resident_score\": [resident_scores[row[\"candidate_id\"]] for row in prediction_rows],\n", + "})\n", + "score_comparison[\"absolute_delta\"] = abs(score_comparison.saved_feature_score - score_comparison.resident_score)\n", + "score_comparison[\"decision_flip\"] = ((score_comparison.saved_feature_score >= threshold)\n", + " != (score_comparison.resident_score >= threshold))\n", + "display(score_comparison.groupby(\"kind\").agg(\n", + " candidates=(\"candidate_id\", \"size\"), maximum_score_delta=(\"absolute_delta\", \"max\"),\n", + " decision_flips=(\"decision_flip\", \"sum\"),\n", + "))\n", + "score_comparison.to_csv(RUNS / \"saved-vs-resident-scores.csv\", index=False)" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-43", + "metadata": {}, + "source": [ + "## 7. Select native CUDA C++ implementations · 31–35 minutes\n", + "\n", + "The numerical backend and the process executor are independent choices. Native\n", + "implementations use precompiled CUDA kernels and CUDA libraries while retaining\n", + "CuPy-owned buffers. `auto` does not select these paths automatically.\n", + "\n", + "| Operation | Explicit selection | Boundary |\n", + "|---|---|---|\n", + "| xDR compressed-pixel restoration | `postprocess=\"native\"` | GZIP_1/GZIP_2 tiles; reader selection is separate |\n", + "| xRep mapping expansion and reprojection | `backend=\"native\"` | Coarse WCS evaluation remains on CPU |\n", + "| xPois source selection and constant-kernel solve | `backend=\"native\"` | Local CLI/device API; batch CLI currently accepts CuPy, Numba-CUDA or cuTile |\n", + "| xFit Gaussian preparation, LM, and covariance | `backend=\"native\"` | Analytic Gaussian models; also works inside Dragon workers |\n", + "\n", + "The existing resident pipeline can select **native xFit**; its xPois stage remains\n", + "CuPy. No claim is made that the entire pipeline, plotting, or all dependencies\n", + "avoid JIT compilation. Compare the same model, precision, solver policy and data.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-44", + "metadata": {}, + "outputs": [], + "source": [ + "compressed_target = Path(data_manifest[\"pairs\"][0][\"target_compressed\"])\n", + "gzip_cupy = read_fits_images(compressed_target, [HDU], reader=\"xdr\", device=True,\n", + " xdr_options={\"postprocess\": \"fused\"})\n", + "gzip_native = read_fits_images(compressed_target, [HDU], reader=\"xdr\", device=True,\n", + " xdr_options={\"postprocess\": \"native\"})\n", + "print(compare_arrays(cp.asnumpy(gzip_cupy.arrays[0]), cp.asnumpy(gzip_native.arrays[0]),\n", + " rtol=0, atol=0, label=\"xDR lossless native restoration\"))\n", + "print(compare_arrays(target, cp.asnumpy(gzip_native.arrays[0]),\n", + " rtol=0, atol=0, label=\"xDR native decoded / original uncompressed pixels\"))\n", + "\n", + "os.environ[\"COMPRESSED_TARGET\"] = str(compressed_target)" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-45", + "metadata": {}, + "source": [ + "The xDR CLI counterpart is a decoding benchmark; it does not export pixel\n", + "arrays. The API cell above checks exact decoded values. `--skip-gds-read` skips\n", + "only the separate raw-storage phase, not FITS decoding." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-46", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xdr-native.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xdr-native.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " cuphoton xdr benchmark-fits \"$COMPRESSED_TARGET\" --hdu-indices 1 \\\n", + " --iterations 1 --native-plan-threads 1 --native-read-threads 1 \\\n", + " --xdr-postprocess native --skip-gds-read --output-json \"$RUNS/xdr-native.json\" >\"$RUNS/xdr-native.log\" 2>&1" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-47", + "metadata": {}, + "outputs": [], + "source": [ + "native_aligned = reproject_stack(sources, stack_spec, backend=\"native\")\n", + "print(compare_arrays(aligned.images, native_aligned.images, label=\"xRep CuPy / native\"))\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-48", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xrep-native.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xrep-native.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " cuphoton xrep reproject-stack \\\n", + " --inputs \"$REFERENCE,$RAW_TARGET\" --hdu 1 \\\n", + " --target-wcs \"$REFERENCE\" --target-hdu 1 \\\n", + " --backend native --fits-reader xdr --interpolation lanczos3 \\\n", + " --mapping-grid-step 1 --write-fits \\\n", + " --output-dir \"$RUNS\" --name xrep-native >\"$RUNS/xrep-native.log\" 2>&1" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-49", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"xrep-native: launcher-to-exit seconds:\", float((RUNS / \"xrep-native.elapsed\").read_text()))\n", + "native_cli_aligned = np.load(RUNS / \"xrep-native\" / \"artifacts\" / \"reprojected_stack.npy\")\n", + "print(compare_arrays(native_aligned.images, native_cli_aligned,\n", + " label=\"xRep native Python / CLI\"))" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-50", + "metadata": {}, + "outputs": [], + "source": [ + "native_subtraction = solve_constant_kernel_device(\n", + " reference_device, target_device, components, backend=\"native\", **solve_options\n", + ")\n", + "print(compare_arrays(difference, cp.asnumpy(native_subtraction.residual),\n", + " label=\"xPois CuPy / native\"))\n", + "_ = image_grid([difference, cp.asnumpy(native_subtraction.residual),\n", + " difference - cp.asnumpy(native_subtraction.residual)],\n", + " [\"CuPy difference\", \"Native difference\", \"Numerical difference\"], diverging=True)\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-51", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xpois-native-cli.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xpois-native-cli.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " cuphoton xpois fit-kernel --backend native --solver constant \\\n", + " --reference \"$REFERENCE\" --reference-hdu 1 --target \"$TARGET\" --target-hdu 1 \\\n", + " --variance \"$VARIANCE\" --variance-hdu 1 --fit-mask \"$FIT_MASK\" \\\n", + " --kernel-height 15 --kernel-width 15 --basis-sigmas 1.5 --basis-degrees 0 \\\n", + " --background-degree 0 --fits-reader xdr --no-review \\\n", + " --output-dir \"$RUNS\" --name xpois-native-cli >\"$RUNS/xpois-native-cli.log\" 2>&1" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-52", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"xpois-native-cli: launcher-to-exit seconds:\", float((RUNS / \"xpois-native-cli.elapsed\").read_text()))\n", + "native_cli_difference = np.load(RUNS / \"xpois-native-cli\" / \"artifacts\" / \"residual.npy\")\n", + "print(compare_arrays(cp.asnumpy(native_subtraction.residual), native_cli_difference,\n", + " label=\"xPois native Python / CLI\"))" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-53", + "metadata": {}, + "source": [ + "Native xPois also moves compact-source filtering and scoring into precompiled\n", + "CUDA. Compare its selected centers and mask with the ordinary GPU-array route.\n", + "This diagnostic mask is independent of the fixed injection-exclusion mask used\n", + "for all subtraction comparisons above; we do not change the scientific inputs.\n", + "This source-selection call has no exact standalone CLI equivalent; the\n", + "`fit-kernel` command above compares the same fixed-mask solve as the Python API.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-54", + "metadata": {}, + "outputs": [], + "source": [ + "from cuphoton.xpois import build_compact_source_stamp_mask\n", + "\n", + "selection_options = dict(valid_mask=solve_options[\"fit_mask\"], stamp_size=31, max_stamps=8)\n", + "# CuPy input selects the GPU-array route; this API names its modes auto/native.\n", + "selection_gpu = build_compact_source_stamp_mask(reference_device, **selection_options)\n", + "selection_native = build_compact_source_stamp_mask(\n", + " reference_device, backend=\"native\", **selection_options\n", + ")\n", + "assert selection_native.centers == selection_gpu.centers\n", + "np.testing.assert_array_equal(cp.asnumpy(selection_native.mask), cp.asnumpy(selection_gpu.mask))\n", + "print(\"Identical selected centers:\", selection_native.centers)\n", + "_ = image_grid([reference, cp.asnumpy(selection_native.mask)],\n", + " [\"Reference: compact-source selection\", \"Native selected fit regions\"], columns=2)\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-55", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/xfit-native.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/xfit-native.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " dragon -s -t tcp -o tcp cuphoton xfit fit-dipoles \\\n", + " --executor dragon --input \"$XFIT_INPUT\" --model gaussian --mode difference \\\n", + " --backend native --compute-dtype float64 --solver-version v0.2 \\\n", + " --chunk-size 32 --max-evaluations 400 \\\n", + " --output-dir \"$RUNS/xfit-native\" --max-workers \"$WORKERS\" >\"$RUNS/xfit-native.log\" 2>&1" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-56", + "metadata": {}, + "source": [ + "For an allocated cluster, replace the `dragon -s ...` command above with\n", + "one of these complete commands; retain the Bash cell's timing and log redirection.\n", + "Shared absolute paths must exist on every host.\n", + "\n", + "```bash\n", + "# Slurm: run inside an interactive allocation.\n", + "dragon --wlm slurm --nodes \"$NODES\" -t tcp -o tcp cuphoton xfit fit-dipoles \\\n", + " --executor dragon --input \"$XFIT_INPUT\" --model gaussian --mode difference \\\n", + " --backend native --compute-dtype float64 --solver-version v0.2 \\\n", + " --chunk-size 32 --max-evaluations 400 \\\n", + " --output-dir \"$RUNS/xfit-native\" --max-workers \"$WORKERS\"\n", + "\n", + "# SSH: use the host file for dedicated, authorized hosts.\n", + "dragon --wlm ssh --nodes \"$NODES\" --hostfile \"$HOSTFILE\" -t tcp -o tcp cuphoton xfit fit-dipoles \\\n", + " --executor dragon --input \"$XFIT_INPUT\" --model gaussian --mode difference \\\n", + " --backend native --compute-dtype float64 --solver-version v0.2 \\\n", + " --chunk-size 32 --max-evaluations 400 \\\n", + " --output-dir \"$RUNS/xfit-native\" --max-workers \"$WORKERS\"\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-57", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"xfit-native: launcher-to-exit seconds:\", float((RUNS / \"xfit-native.elapsed\").read_text()))\n", + "native_fits = pd.read_parquet(RUNS / \"xfit-native\" / \"scientific\" / \"fits.parquet\")\n", + "assert native_fits[\"candidate_id\"].tolist() == fit_table[\"candidate_id\"].tolist()\n", + "candidate_kind = {row[\"candidate_id\"]: row[\"kind\"]\n", + " for item in data_manifest[\"pairs\"] for row in item[\"candidates\"]}\n", + "fit_comparison = pd.DataFrame({\n", + " \"candidate_id\": fit_table[\"candidate_id\"],\n", + " \"kind\": [candidate_kind[c] for c in fit_table[\"candidate_id\"]],\n", + " \"cupy_converged\": fit_table[\"converged\"],\n", + " \"native_converged\": native_fits[\"converged\"],\n", + " \"cupy_uncertainty_valid\": fit_table[\"uncertainty_valid\"],\n", + " \"native_uncertainty_valid\": native_fits[\"uncertainty_valid\"],\n", + "})\n", + "centers = [\"x_pos\", \"y_pos\", \"x_neg\", \"y_neg\"]\n", + "cupy_centers = fit_table[centers].to_numpy()\n", + "native_centers = native_fits[centers].to_numpy()\n", + "fit_comparison[\"center_max_abs_delta_px\"] = np.max(np.abs(cupy_centers - native_centers), axis=1)\n", + "fit_comparison[\"strict_center_failure\"] = ~np.isclose(\n", + " cupy_centers, native_centers, rtol=1e-5, atol=1e-7, equal_nan=True,\n", + ").all(axis=1)\n", + "center_errors = [f\"{name}_standard_error\" for name in centers]\n", + "fit_comparison[\"cupy_center_standard_error_max_px\"] = fit_table[center_errors].max(axis=1)\n", + "fit_comparison[\"native_center_standard_error_max_px\"] = native_fits[center_errors].max(axis=1)\n", + "print(\"All-candidate center comparison: rtol=1e-5, atol=1e-7 pixel\")\n", + "display(fit_comparison.groupby(\"kind\").agg(\n", + " candidates=(\"candidate_id\", \"size\"),\n", + " cupy_converged=(\"cupy_converged\", \"sum\"), native_converged=(\"native_converged\", \"sum\"),\n", + " cupy_valid=(\"cupy_uncertainty_valid\", \"sum\"), native_valid=(\"native_uncertainty_valid\", \"sum\"),\n", + " center_max_abs_delta_px=(\"center_max_abs_delta_px\", \"max\"),\n", + " strict_center_failures=(\"strict_center_failure\", \"sum\"),\n", + "))\n", + "display(fit_comparison.nlargest(6, \"center_max_abs_delta_px\")[[\n", + " \"candidate_id\", \"kind\", \"center_max_abs_delta_px\", \"strict_center_failure\",\n", + " \"cupy_center_standard_error_max_px\", \"native_center_standard_error_max_px\",\n", + "]])\n", + "identified = ((fit_comparison[\"kind\"] == \"moving_source\")\n", + " & fit_comparison[\"cupy_converged\"] & fit_comparison[\"native_converged\"]\n", + " & fit_comparison[\"cupy_uncertainty_valid\"] & fit_comparison[\"native_uncertainty_valid\"])\n", + "assert identified.any(), \"No identified moving-source fits to compare\"\n", + "print(compare_arrays(fit_table.loc[identified, centers].to_numpy(),\n", + " native_fits.loc[identified, centers].to_numpy(),\n", + " rtol=1e-4, atol=1e-5, label=\"xFit CuPy / native identified centers\"))\n", + "fit_comparison.to_json(RUNS / \"native-fit-comparison.json\", orient=\"records\", indent=2)\n", + "_ = summarize_run(RUNS / \"xfit-native\")" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-58", + "metadata": {}, + "source": [ + "The all-candidate table reports center differences and strict comparison failure counts\n", + "for every injected class. A Gaussian dipole is a mismatched model for sharp or\n", + "track-like detector artifacts; poorly constrained fits can have large formal\n", + "center errors even when their convergence and uncertainty-valid flags are true.\n", + "Inspect those rows separately from the identified moving-source assertion.\n", + "Numerical agreement does not make a mismatched artifact fit scientifically identifiable.\n", + "\n", + "To place native xFit inside the resident pipeline, only its backend field changes.\n", + "The replay below retains\n", + "solver policy v0.2 and the exact checkpoint, pair inputs, and other settings.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-59", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "trap 'tail -n 40 \"$RUNS/pipeline-native.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/pipeline-native.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " dragon -s -t tcp -o tcp cuphoton xscan run-pipeline \\\n", + " --executor dragon --manifest \"$NATIVE_PIPELINE_MANIFEST\" \\\n", + " --output-dir \"$RUNS\" --name pipeline-native \\\n", + " --warmup-rounds 1 --measure-rounds 3 --max-workers \"$WORKERS\" >\"$RUNS/pipeline-native.log\" 2>&1" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-60", + "metadata": {}, + "source": [ + "For an allocated cluster, replace the `dragon -s ...` command above with\n", + "one of these complete commands; retain the Bash cell's timing and log redirection.\n", + "Shared absolute paths must exist on every host.\n", + "\n", + "```bash\n", + "# Slurm: run inside an interactive allocation.\n", + "dragon --wlm slurm --nodes \"$NODES\" -t tcp -o tcp cuphoton xscan run-pipeline \\\n", + " --executor dragon --manifest \"$NATIVE_PIPELINE_MANIFEST\" \\\n", + " --output-dir \"$RUNS\" --name pipeline-native \\\n", + " --warmup-rounds 1 --measure-rounds 3 --max-workers \"$WORKERS\"\n", + "\n", + "# SSH: use the host file for dedicated, authorized hosts.\n", + "dragon --wlm ssh --nodes \"$NODES\" --hostfile \"$HOSTFILE\" -t tcp -o tcp cuphoton xscan run-pipeline \\\n", + " --executor dragon --manifest \"$NATIVE_PIPELINE_MANIFEST\" \\\n", + " --output-dir \"$RUNS\" --name pipeline-native \\\n", + " --warmup-rounds 1 --measure-rounds 3 --max-workers \"$WORKERS\"\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-61", + "metadata": {}, + "outputs": [], + "source": [ + "print(\"pipeline-native: launcher-to-exit seconds:\", float((RUNS / \"pipeline-native.elapsed\").read_text()))\n", + "native_pipeline_path = Path(prepared[\"native_pipeline_manifest\"])\n", + "_ = summarize_run(RUNS / \"pipeline-native\")\n", + "native_config, _ = load_pipeline_manifest(native_pipeline_path)\n", + "native_round = sorted((RUNS / \"pipeline-native\" / \"rounds\").glob(\"measure-*\"))[-1]\n", + "native_scores = []\n", + "for item in pipeline_items:\n", + " payload = load_json(native_round / \"items\" / item.item_id / \"summary.json\")\n", + " observed = decode_device_pipeline_evidence(payload[\"scientific_evidence\"], config=native_config)\n", + " expected = decode_device_pipeline_evidence(local_by_id[item.item_id][\"scientific_evidence\"],\n", + " config=pipeline_config)\n", + " native_scores.append(compare_arrays(\n", + " expected[\"xscan.probabilities\"], observed[\"xscan.probabilities\"],\n", + " rtol=1e-4, atol=1e-5, label=f\"{item.item_id}: CuPy/native pipeline scores\"\n", + " ))\n", + "display(pd.DataFrame(native_scores))" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-62", + "metadata": {}, + "source": [ + "## Optional: discover candidates and build a richer catalog · 5–7 minutes\n", + "\n", + "The existing [transient-chain example](https://github.com/NVIDIA/cuPhoton/blob/b17cf8a30fa64c466c3e9b62ad98eccbb8f87cab/examples/transient-chain/README.md) starts from\n", + "FITS pairs, aligns them, constructs a fit mask, detects residual peaks,\n", + "and fits candidates with mask/variance handling, quality flags, propagated\n", + "uncertainties, and single-source refits. It also supports a compatible image-only\n", + "checkpoint. Our injection-trained **fusion** checkpoint is a different model\n", + "contract, so this appendix intentionally ends after xFit. The example also offers\n", + "star-based registration refinement; the prepared injection demo disables it so\n", + "fitting an affine transform cannot absorb the deliberately injected motion.\n", + "\n", + "The chain is an example application with its own `launch.py`, not an invented\n", + "`cuphoton` subcommand. Its present numerical path is CuPy; it does not expose the\n", + "native selectors demonstrated above. The uncertainty budget describes the\n", + "supplied noise model, and correlated or reused background pixels still limit\n", + "interpretation. The inputs here remain controlled injections on real backgrounds.\n", + "\n", + "Set `CUPHOTON_DEMO_TRANSIENT_CHAIN=1` before starting Jupyter to execute the\n", + "optional Bash cell. The separate `examples/transient-chain` package must be\n", + "installed in the shared environment, as shown in the README." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-63", + "metadata": {}, + "outputs": [], + "source": [ + "chain = prepared.get(\"transient_chain\")\n", + "RUN_TRANSIENT_CHAIN = os.environ.get(\"CUPHOTON_DEMO_TRANSIENT_CHAIN\", \"1\") == \"1\"\n", + "if RUN_TRANSIENT_CHAIN and chain is None:\n", + " raise RuntimeError(\"Optional chain inputs are missing; rerun prepare.py in a new output directory.\")\n", + "if chain is not None:\n", + " os.environ.update({\n", + " \"TRANSIENT_LAUNCHER\": str(REPO / \"examples\" / \"transient-chain\" / \"launch.py\"),\n", + " \"TRANSIENT_CONFIG\": chain[\"config\"], \"TRANSIENT_SELECTIONS\": chain[\"selections\"],\n", + " })" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-64", + "metadata": {}, + "outputs": [], + "source": [ + "%%bash\n", + "set -euxo pipefail\n", + "if [[ ${CUPHOTON_DEMO_TRANSIENT_CHAIN:-0} != 1 ]]; then\n", + " echo \"Optional transient-chain skipped; set CUPHOTON_DEMO_TRANSIENT_CHAIN=1 to run.\"\n", + " exit 0\n", + "fi\n", + "trap 'tail -n 40 \"$RUNS/transient-chain.log\"' EXIT\n", + "/usr/bin/time -f '%e' -o \"$RUNS/transient-chain.elapsed\" \\\n", + " timeout --signal=TERM --kill-after=10s 600s \\\n", + " dragon -s -t tcp -o tcp python \"$TRANSIENT_LAUNCHER\" \\\n", + " --executor dragon --config \"$TRANSIENT_CONFIG\" --selections \"$TRANSIENT_SELECTIONS\" \\\n", + " --output-dir \"$RUNS\" --name transient-chain --max-workers \"$WORKERS\" >\"$RUNS/transient-chain.log\" 2>&1" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-65", + "metadata": {}, + "source": [ + "For an allocated cluster, replace the `dragon -s ...` command above with\n", + "one of these complete commands; retain the Bash cell's timing and log redirection.\n", + "Shared absolute paths must exist on every host.\n", + "\n", + "```bash\n", + "# Slurm: run inside an interactive allocation.\n", + "dragon --wlm slurm --nodes \"$NODES\" -t tcp -o tcp python \"$TRANSIENT_LAUNCHER\" \\\n", + " --executor dragon --config \"$TRANSIENT_CONFIG\" --selections \"$TRANSIENT_SELECTIONS\" \\\n", + " --output-dir \"$RUNS\" --name transient-chain --max-workers \"$WORKERS\"\n", + "\n", + "# SSH: use the host file for dedicated, authorized hosts.\n", + "dragon --wlm ssh --nodes \"$NODES\" --hostfile \"$HOSTFILE\" -t tcp -o tcp python \"$TRANSIENT_LAUNCHER\" \\\n", + " --executor dragon --config \"$TRANSIENT_CONFIG\" --selections \"$TRANSIENT_SELECTIONS\" \\\n", + " --output-dir \"$RUNS\" --name transient-chain --max-workers \"$WORKERS\"\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "sc26-66", + "metadata": {}, + "outputs": [], + "source": [ + "if RUN_TRANSIENT_CHAIN:\n", + " print(\"transient-chain: launcher-to-exit seconds:\", float((RUNS / \"transient-chain.elapsed\").read_text()))\n", + " _ = summarize_run(RUNS / \"transient-chain\")\n", + " catalogs = list((RUNS / \"transient-chain\").glob(\"**/catalog.parquet\"))\n", + " catalog = pd.read_parquet(catalogs[0])\n", + " display(catalog[[\"candidate_id\", \"x\", \"y\", \"peak_abs_sigma\", \"amplitude\", \"amplitude_err\",\n", + " \"probability\", \"decision\"]].head(12))" + ] + }, + { + "cell_type": "markdown", + "id": "sc26-67", + "metadata": {}, + "source": [ + "The completed run leaves source provenance, manifests, model evaluation, launch\n", + "logs, scientific comparisons, and worker records beside the data. The plots show\n", + "what each stage calculated; the recorded host/GPU identities show where it ran.\n", + "For larger observations, retain the same contracts and increase the number of\n", + "independent image pairs before changing worker sharing or transport settings.\n", + "\n", + "Further reading: [Dragon architecture](https://github.com/NVIDIA/cuPhoton/blob/b17cf8a30fa64c466c3e9b62ad98eccbb8f87cab/docs/dragon.md),\n", + "[launch guide](https://github.com/NVIDIA/cuPhoton/blob/b17cf8a30fa64c466c3e9b62ad98eccbb8f87cab/docs/distributed-execution.md),\n", + "[transport and timing](https://github.com/NVIDIA/cuPhoton/blob/b17cf8a30fa64c466c3e9b62ad98eccbb8f87cab/docs/dragon-performance.md),\n", + "[native xFit](https://github.com/NVIDIA/cuPhoton/blob/b17cf8a30fa64c466c3e9b62ad98eccbb8f87cab/docs/components/xfit.md#optional-native-cuda-backend), and\n", + "[xImage reconstruction](https://github.com/NVIDIA/cuPhoton/blob/b17cf8a30fa64c466c3e9b62ad98eccbb8f87cab/docs/components/ximage.md) for the separate problem\n", + "of reconstructing a common scene from registered exposures with supplied PSFs.\n" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "cuPhoton SC26", + "language": "python", + "name": "cuphoton-sc26" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.12" + }, + "license": "Apache-2.0" + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/syllabi/sc26__8_hours.ipynb b/notebooks/syllabi/sc26__8_hours.ipynb index 70c6e77..50e8148 100644 --- a/notebooks/syllabi/sc26__8_hours.ipynb +++ b/notebooks/syllabi/sc26__8_hours.ipynb @@ -23,7 +23,8 @@ "| 10 | [Mini-App: CppJIT - CUDA C++ Kernel](../gpu-mini-app/10__cosmic_web__cppjit__cuda_kernel.ipynb) | - | CppJIT, CUDA |\n", "| 11 | [Mini-App: Synthesis](../gpu-mini-app/11__cosmic_web__synthesis.ipynb) | - | - |\n", "| - | Domain Science Examples | [Notebooks](https://compiler-research.org/live-cpp-tutorials/) | - |\n", - "| 12 | [DragonHPC/cuPhoton](../distributed/12__dragonhpc_cuphoton__workflow.ipynb) (placeholder) | - | DragonHPC, cuPhoton |\n", + "| 12 | [DragonHPC](../distributed/12__dragonhpc_cuphoton__intro.ipynb) | [Click](../distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb) | DragonHPC |\n", + "| 13 | [DragonHPC/cuPhoton](../distributed/13__dragonhpc_cuphoton__workflow.ipynb) | [Click](../distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb) | DragonHPC, cuPhoton |\n", "\n", "### Materials\n", "\n", @@ -44,7 +45,8 @@ "- Programming models in Python for GPU applications: array expressions, fusion, library iterators, kernel authoring, and interoperability with CUDA C++ kernels.\n", "- Reading an application's profile with Nsight Systems and Nsight Compute.\n", "- Case studies of horizontal Python and C++ integration in domain sciences such as cancer research and high energy physics.\n", - "- cuPhoton and DragonHPC (placeholder).\n", + "- DragonHPC fundamentals enabling `multiprocessing` to scale across HPC multi-node resources.\n", + "- cuPhoton astronomical image processing workflows orchestrated using DragonHPC.\n", "\n", "Attendees are expected to have general knowledge of HPC and Python programming. Some familiarity with NumPy and C/C++ is helpful but not required." ] diff --git a/test/test_packages.py b/test/test_packages.py index a667608..6195c74 100644 --- a/test/test_packages.py +++ b/test/test_packages.py @@ -344,7 +344,7 @@ def test_dragon_and_cuphoton(): assert torch.cuda.is_available() assert Path(os.environ["CUPHOTON_DEMO_REPO"], "examples", "dragon-imaging-pipeline", "demo.py").is_file() result = subprocess.run(["dragon", "--version"], capture_output=True, text=True, check=True) - assert "Dragon Version 0.14.2" in result.stdout, result.stdout + result.stderr + assert "Dragon Version 0.15.0" in result.stdout, result.stdout + result.stderr def test_mpi4py(): From ec83062b51572e83c6af049c97fd94ad72719c20 Mon Sep 17 00:00:00 2001 From: Aaron Jomy Date: Sat, 14 Nov 2026 01:50:05 +0100 Subject: [PATCH 2/6] Run the DragonHPC notebooks through the format check. brev/check-notebooks.py --fix sets the python3 kernelspec, the pinned language version and the metadata keys on the four new notebooks, so the Checks workflow passes and test_notebooks.py can start their kernel. Signed-off-by: Aaron Jomy --- .../12__dragonhpc_cuphoton__intro.ipynb | 12 +++++++++--- .../13__dragonhpc_cuphoton__workflow.ipynb | 15 ++++++++++----- .../12__dragonhpc_cuphoton__intro__SOLUTION.ipynb | 12 +++++++++--- ...__dragonhpc_cuphoton__workflow__SOLUTION.ipynb | 15 ++++++++++----- 4 files changed, 38 insertions(+), 16 deletions(-) diff --git a/notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb b/notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb index 9f79f9a..a789aa3 100644 --- a/notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb +++ b/notebooks/distributed/12__dragonhpc_cuphoton__intro.ipynb @@ -695,10 +695,16 @@ } ], "metadata": { + "accelerator": "GPU", + "colab": { + "gpuType": "T4", + "provenance": [], + "toc_visible": true + }, "kernelspec": { - "display_name": "cuPhoton SC26", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "cuphoton-sc26" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -710,7 +716,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.12" + "version": "3.11.7" } }, "nbformat": 4, diff --git a/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb index 687c2a0..7bb03a1 100644 --- a/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb +++ b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb @@ -1595,10 +1595,16 @@ } ], "metadata": { + "accelerator": "GPU", + "colab": { + "gpuType": "T4", + "provenance": [], + "toc_visible": true + }, "kernelspec": { - "display_name": "cuPhoton SC26", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "cuphoton-sc26" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -1610,9 +1616,8 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.12" - }, - "license": "Apache-2.0" + "version": "3.11.7" + } }, "nbformat": 4, "nbformat_minor": 5 diff --git a/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb b/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb index e8ad32f..9feb38a 100644 --- a/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb +++ b/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb @@ -859,10 +859,16 @@ } ], "metadata": { + "accelerator": "GPU", + "colab": { + "gpuType": "T4", + "provenance": [], + "toc_visible": true + }, "kernelspec": { - "display_name": "cuPhoton SC26", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "cuphoton-sc26" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -874,7 +880,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.12" + "version": "3.11.7" } }, "nbformat": 4, diff --git a/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb index 687c2a0..7bb03a1 100644 --- a/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb +++ b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb @@ -1595,10 +1595,16 @@ } ], "metadata": { + "accelerator": "GPU", + "colab": { + "gpuType": "T4", + "provenance": [], + "toc_visible": true + }, "kernelspec": { - "display_name": "cuPhoton SC26", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "cuphoton-sc26" + "name": "python3" }, "language_info": { "codemirror_mode": { @@ -1610,9 +1616,8 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.12" - }, - "license": "Apache-2.0" + "version": "3.11.7" + } }, "nbformat": 4, "nbformat_minor": 5 From f3c5d2c416086e6302c16f34ffbf0e4c7fae8121 Mon Sep 17 00:00:00 2001 From: Aaron Jomy Date: Sat, 14 Nov 2026 01:50:40 +0100 Subject: [PATCH 3/6] Move the DDict figure to LFS and fix its path in the SOLUTION. The PNG was committed as a raw blob although .gitattributes routes *.png through git-lfs; it is now a pointer. The SOLUTION notebook lives one directory down, so its image reference gains a ../ prefix. Signed-off-by: Aaron Jomy --- .../distributed/images/ddict_overview.png | Bin 65569 -> 130 bytes ..._dragonhpc_cuphoton__intro__SOLUTION.ipynb | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/notebooks/distributed/images/ddict_overview.png b/notebooks/distributed/images/ddict_overview.png index 123b2804003b4e16afd4642300f5892c41a5b6e5..945f46a0fc22d365ebb27616a802c98061bef3a3 100644 GIT binary patch literal 130 zcmWN?K@!3s3;@78uiyigLJTDRO@tuKsO<>$;OliSd+K}i{bk#n$Jm^^_j!5LvHWkJ z+miRE8;53hdb9UpN0WeY1BI-Zuo5f58gkVD%#ezp&zM-kwXVV-5{WQSkwQ?&Q%H;{ MnbE&$BVuIp1KPnR+W-In literal 65569 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�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 R(ZogIXP{@aE0bt@<}dH2nic>6 diff --git a/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb b/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb index 9feb38a..70a2499 100644 --- a/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb +++ b/notebooks/distributed/solutions/12__dragonhpc_cuphoton__intro__SOLUTION.ipynb @@ -557,7 +557,7 @@ "of the data is transparent to the user. When user code interacts with it, the\n", "code does not need to know the location of any key-value pair stored in it.\n", "\n", - "\n", + "\n", "\n", "Key characteristics:\n", "- Standard `dict`-like interface (`d[key] = val`, `d[key]`, `del d[key]`, `len(d)`, ...)\n", From d682a467c0072c1b33dfe0ffa0658170adf592de Mon Sep 17 00:00:00 2001 From: Aaron Jomy Date: Sat, 14 Nov 2026 01:51:09 +0100 Subject: [PATCH 4/6] Fix the demo repository path in the workflow notebook. The setup cell gave CUPHOTON_DEMO_REPO a placeholder default, /path/to/checkout/repo/cuPhoton, which disabled the search from the working directory and failed with a path nobody has. The variable is read without a default again, as on main; the image sets it to /opt/cuPhoton. Signed-off-by: Aaron Jomy --- notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb | 2 +- .../solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb index 7bb03a1..78e8659 100644 --- a/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb +++ b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb @@ -86,7 +86,7 @@ "from IPython.display import display\n", "\n", "# A served output copy may live elsewhere; point it at the source checkout.\n", - "repo_override = os.environ.get(\"CUPHOTON_DEMO_REPO\", \"/path/to/checkout/repo/cuPhoton\")\n", + "repo_override = os.environ.get(\"CUPHOTON_DEMO_REPO\")\n", "search_roots = ([Path(repo_override).expanduser().resolve()] if repo_override\n", " else [Path.cwd(), *Path.cwd().parents])\n", "EXAMPLE = next((\n", diff --git a/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb index 7bb03a1..78e8659 100644 --- a/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb +++ b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb @@ -86,7 +86,7 @@ "from IPython.display import display\n", "\n", "# A served output copy may live elsewhere; point it at the source checkout.\n", - "repo_override = os.environ.get(\"CUPHOTON_DEMO_REPO\", \"/path/to/checkout/repo/cuPhoton\")\n", + "repo_override = os.environ.get(\"CUPHOTON_DEMO_REPO\")\n", "search_roots = ([Path(repo_override).expanduser().resolve()] if repo_override\n", " else [Path.cwd(), *Path.cwd().parents])\n", "EXAMPLE = next((\n", From 63a6b6852dc73dde981c99b8179c15f9f80bb1e7 Mon Sep 17 00:00:00 2001 From: Aaron Jomy Date: Sat, 14 Nov 2026 01:51:35 +0100 Subject: [PATCH 5/6] Handle the transient-chain environment variable consistently. The Python cell defaulted CUPHOTON_DEMO_TRANSIENT_CHAIN to 1 while the Bash cell that runs the chain defaulted it to 0, so with the variable unset the chain was skipped and the next cell failed on the missing transient-chain.elapsed. Both cells now default to off, as the prose above them says. Signed-off-by: Aaron Jomy --- notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb | 2 +- .../solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb index 78e8659..d32d9a1 100644 --- a/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb +++ b/notebooks/distributed/13__dragonhpc_cuphoton__workflow.ipynb @@ -1505,7 +1505,7 @@ "outputs": [], "source": [ "chain = prepared.get(\"transient_chain\")\n", - "RUN_TRANSIENT_CHAIN = os.environ.get(\"CUPHOTON_DEMO_TRANSIENT_CHAIN\", \"1\") == \"1\"\n", + "RUN_TRANSIENT_CHAIN = os.environ.get(\"CUPHOTON_DEMO_TRANSIENT_CHAIN\", \"0\") == \"1\"\n", "if RUN_TRANSIENT_CHAIN and chain is None:\n", " raise RuntimeError(\"Optional chain inputs are missing; rerun prepare.py in a new output directory.\")\n", "if chain is not None:\n", diff --git a/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb index 78e8659..d32d9a1 100644 --- a/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb +++ b/notebooks/distributed/solutions/13__dragonhpc_cuphoton__workflow__SOLUTION.ipynb @@ -1505,7 +1505,7 @@ "outputs": [], "source": [ "chain = prepared.get(\"transient_chain\")\n", - "RUN_TRANSIENT_CHAIN = os.environ.get(\"CUPHOTON_DEMO_TRANSIENT_CHAIN\", \"1\") == \"1\"\n", + "RUN_TRANSIENT_CHAIN = os.environ.get(\"CUPHOTON_DEMO_TRANSIENT_CHAIN\", \"0\") == \"1\"\n", "if RUN_TRANSIENT_CHAIN and chain is None:\n", " raise RuntimeError(\"Optional chain inputs are missing; rerun prepare.py in a new output directory.\")\n", "if chain is not None:\n", From 32185db17c674d2d7fde56b87651fae00893b4bc Mon Sep 17 00:00:00 2001 From: Aaron Jomy Date: Sat, 14 Nov 2026 20:04:05 +0100 Subject: [PATCH 6/6] Give the containers the shared memory Dragon 0.15 needs. Signed-off-by: Aaron Jomy --- brev/docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brev/docker-compose.yml b/brev/docker-compose.yml index 589ffe9..b7e8c34 100644 --- a/brev/docker-compose.yml +++ b/brev/docker-compose.yml @@ -9,7 +9,7 @@ x-gpu: &gpu ulimits: memlock: -1 stack: 67108864 - shm_size: 1g + shm_size: 6g # Dragon 0.15 creates its memory pool in shared memory and asks for 6 GB. deploy: resources: reservations: