Your First Program

Start a KCoral server, then submit a program that adds one to a four-element tensor on its GPU (graphics processing unit) and returns the result.

Required hardware

You need one Linux machine with an NVIDIA GPU and a compatible driver. Install the GPU server environment on it; this also installs the client. The example uses PyTorch, a tensor library included in that environment, and does not compile a custom kernel.

The steps below run the server and client on that same machine, in two terminals. A CPU (central processing unit) compilation server cannot run this program: the uploaded function checks that the tensor is on a GPU before doing arithmetic.

Launch the server

In the first terminal, open the repository directory, activate the installed environment, and start one worker on GPU 0:

source .venv/bin/activate
kcoral server --device gpu --gpus 0 --workers-per-gpu 1 --host 127.0.0.1 --port 8000

GPU 0 is the first GPU listed by nvidia-smi. Wait for server startup to finish and leave this terminal running. The client will connect to http://127.0.0.1:8000.

Submit the program

In a second terminal, open the same repository directory and activate the environment:

source .venv/bin/activate

Save the following complete program as first_program.py:

"""Upload a tensor, add one on the GPU, and return the result."""

import os

import numpy as np

from kcoral import Client, Program

SOURCE = """
def add_one(x):
    if not x.is_cuda:
        raise RuntimeError("This program requires a GPU tensor")
    return x + 1
"""


def build_program() -> Program:
    program = Program()
    module = program.upload(id="module", kind="module", source=SOURCE)
    add_one = program.get_function(id="add_one", module=module, name="add_one")
    x = program.upload(id="x", kind="tensor", value=np.arange(4, dtype=np.float32))
    y = program.run(id="y", fn=add_one, args=[x])
    program.return_(key="output", value=y)
    return program


def main() -> None:
    with Client(os.environ.get("KCORAL_URL", "http://localhost:8000")) as client:
        result = client.execute(build_program(), timeout_seconds=30)
    if not result.completed:
        raise SystemExit(f"Program failed: {result.error}")
    np.testing.assert_array_equal(result.results["output"], np.arange(1, 5, dtype=np.float32))
    print(result.status)
    print(result.results["output"])


if __name__ == "__main__":
    main()

You can also download first_program.py. Run it from the directory where you saved it:

KCORAL_URL=http://127.0.0.1:8000 python first_program.py

Expected output:

COMPLETED
[1. 2. 3. 4.]

The program checks that the request completed and that the returned array has the expected values. When you finish, press Ctrl+C in the server terminal to stop it.

Use a remote server

To submit from another machine, start the server with --host 0.0.0.0 so it listens beyond the local machine. Install the client on the submitting machine, save the same program there, and set KCORAL_URL to the server’s reachable address, for example http://192.168.1.10:8000. The client machine does not need a GPU. See Launch the server for more configuration.

How it works

  1. Program.upload(kind="module") sends the source defining add_one.

  2. Program.get_function() selects that function from the uploaded module.

  3. The tensor upload transfers the NumPy input to the server’s GPU.

  4. Program.run() performs the addition on that GPU and binds the result to y.

  5. Program.return_() selects the output for the response. The client decodes it as a CPU NumPy array and checks the values.

The example also checks result.completed before reading the output. Instruction failures are returned as data in result.error; connection failures and request errors raise the exceptions documented in the Python API.

Continue to Write a client program for the builder methods and request lifecycle, or Benchmark a Kernel with KCoral to compile a custom kernel, check correctness and measure its execution.