The whole API surface, in one page
The API is small on purpose. Three things, and you have seen most of the platform.
import eugo.hpc
# 1. The decorator: on a function it makes a task, on a class an actor
@eugo.hpc.distribute
def work(x):
return x * 2
# 2. .remote() starts the work and returns a future; get() turns futures into values
future = work.remote(21)
value = eugo.hpc.get(future) # 42
# 3. options() sets per-call resource requirements
big = work.options(num_cpus=4, num_gpus=1).remote(21)
eugo alone gives you nothingThe top-level eugo namespace is deliberately empty. import eugo.hpc is the import you want.
Why the surface is this small
Eugo puts the decision at the definition site. A function is either distributed or it is not, declared
once with the decorator. The call site then carries one short marker, .remote(...), which starts the work
on the cluster your notebook is connected to (the Connect button in the EugoHPC Manager
panel) and hands back a future at once. There is no executor to create, no pool to size
and no context manager to enter:
futures = [work.remote(x) for x in items]
That is a list comprehension. It is also a thousand-task fan-out across a cluster.
The one thing that changes
Decorating a function changes how you call it, and what the call returns.
Plain function, work(x) | Distributed function, work.remote(x) | |
|---|---|---|
| Returns | The value | A future |
| When the body runs | Immediately, inline | Later, on a worker |
| Blocks the caller | Yes | No |
A future is a handle to a result that does not exist yet. Your code keeps running; get() is where you
wait.
Calling a distributed function the plain way, work(21), is an error rather than a quiet local run:
TypeError: Remote functions cannot be called directly. Instead of running '__main__.work()', try '__main__.work.remote()'.
Everything else in this course follows from that single change.
Where each piece is covered
| Piece | Lesson |
|---|---|
| Tasks and the decorator | Your first distributed task |
Futures and get() | Futures, and when to call get() |
| Many tasks at once | Parallel fan-out |
options() | Requesting CPUs and GPUs |
| Actors | Distributed objects that hold state |
Ray, underneath
Eugo's distributed execution is built on Ray. The decorator is Ray's own remote decorator, so the call forms in
this course (.remote(), .options()) are Ray's, and the rest of Ray stays behind this smaller surface.
Worth knowing for two reasons: Ray's concepts (tasks, actors, object refs) map onto what you are learning, and its documentation can be a useful reference for edge cases. You do not need to know Ray to use Eugo, and the hidden parts are hidden because managing them by hand is what the platform is for.