arkouda.client

Client interface for connecting to and communicating with the Arkouda server.

The arkouda.client module provides the core logic for managing a client-server session in Arkouda. It includes methods to connect, disconnect, send commands, check system status, and retrieve configuration details from the server. The client communicates with the server via ZMQ by default and handles both string and binary message formats.

Key Responsibilities

  • Establish and manage server connections via different Channel types (e.g., ZMQ)

  • Format and send commands using Arkouda’s request-response protocol

  • Retrieve memory and configuration metrics from the server

  • Provide a health check (ruok) and shutdown mechanism

  • Maintain client-side logging, verbosity, and session parameters

  • (Optional) Provide async-style request sending and an async_connect() helper

Classes

Channel

Abstract base class for communication between the client and the server.

ZmqChannel

Default implementation of Channel using ZeroMQ request-reply pattern.

ClientMode, ShellMode, RequestMode, ChannelType

Enum classes defining modes of client interaction, shell type detection, and channel selection.

Functions

connect(…)

Establish a connection to an Arkouda server.

disconnect()

Cleanly disconnect from the server and reset session state.

shutdown()

Shut down the server, delete its symbol table, and disconnect the client.

get_config()

Return server runtime configuration and environment settings.

get_mem_used(), get_mem_avail(), get_mem_status()

Retrieve memory usage and availability statistics from the server.

get_server_commands()

Get a mapping of available server commands and their functions.

print_server_commands()

Print a list of all supported server-side commands.

generate_history(…)

Retrieve interactive shell or notebook command history.

ruok()

Send a health check to the server (“ruok”) and receive status.

Notes

  • This module is foundational to all Arkouda workflows.

  • The generic_msg() function handles message transmission.

  • Clients must call connect() (or async_connect()) before performing any operations.

  • The async additions are fully backward-compatible and purely opt‑in via env var.

Examples

>>> import arkouda as ak
>>> ak.connect()
>>> ak.get_config()
{'serverHostname': 'localhost', 'numLocales': 4, ...}
>>> ak.disconnect()

Functions

connect(→ None)

Connect to a running Arkouda server.

disconnect(→ None)

Disconnect the client from the Arkouda server.

generate_history(→ List[str])

Generate a list of commands executed in the shell/notebook.

get_config(→ Mapping[str, Union[str, int, float]])

Get runtime information about the server.

get_max_array_rank(→ int)

Get the maximum pdarray rank the server was compiled to support.

get_mem_avail(→ int)

Compute the amount of memory available to be used.

get_mem_status(→ List[Mapping[str, Union[str, int, ...)

Retrieve the memory status for each locale.

get_mem_used(→ int)

Compute the amount of memory used by objects in the server's symbol table.

get_registration_config()

Get the registration settings the server was built with.

get_server_commands(→ Mapping[str, str])

Return a dictionary of available server commands and their functions.

print_server_commands()

Print the list of available server commands.

ruok(→ str)

Quick health check that does not require error handling.

shutdown(→ None)

Send a shutdown message and disconnect.

Module Contents

arkouda.client.connect(server: str = 'localhost', port: int = 5555, timeout: int = 0, access_token: str | None = None, connect_url: str | None = None, access_channel: Channel | None = None) → None[source]

Connect to a running Arkouda server.

Parameters:

  • server (str, default "localhost") – Hostname visible to the current machine.

  • port (int, default 5555) – Server port.

  • timeout (int, default 0) – Timeout in seconds for send/receive. If positive, also activates heartbeat monitoring (ZMQ).

  • access_token (str, optional) – Access token for authenticated servers.

  • connect_url (str, optional) – Complete URL in the form tcp://server:port?token=<token_value>.

  • access_channel (Channel, optional) – A pre-constructed channel instance to use instead of the default.

Raises:

  • ConnectionError – If there is an error connecting to the server.

  • ValueError – If connect_url cannot be parsed.

  • RuntimeError – If a server-side error occurs during connect.

Notes

On success, prints the connected address (as seen by the server). If called with an existing connection, the socket will be re-initialized.

arkouda.client.disconnect() → None[source]

Disconnect the client from the Arkouda server.

Raises:

ConnectionError – If there is an error during disconnect.

arkouda.client.generate_history(num_commands: int | None = None, command_filter: str | None = None) → List[str][source]

Generate a list of commands executed in the shell/notebook.

Parameters:

  • num_commands (int, optional) – Number of commands to retrieve from history.

  • command_filter (str, optional) – Filter string to select a subset of commands.

Returns:

List of command strings.

Return type:

list[str]

Examples

>>> import arkouda as ak
>>> ak.get_config()
{'arkoudaVersion': 'v2025.01.13+165.g23ccdfd6c', 'chplVersion': '2.4.0',
    ... 'pythonVersion': '3.13', 'ZMQVersion': '4.3.5', 'HDF5Version': '1.14.4',
    ... 'serverHostname': 'pop-os', 'ServerPort': 5555, 'numLocales': 1,
    ... 'numPUs': 8, 'maxTaskPar': 8, 'physicalMemory': 67258408960,
    ... 'distributionType': 'domain(1,int(64),one)',
    ... 'LocaleConfigs': [{'id': 0, 'name': 'pop-os', 'numPUs': 8,
    ... 'maxTaskPar': 8, 'physicalMemory': 67258408960}], 'authenticate': False,
    ... 'logLevel': 'INFO', 'logChannel': 'FILE', 'regexMaxCaptures': 20,
    ... 'byteorder': 'little', 'autoShutdown': False, 'serverInfoNoSplash': False,
    ... 'maxArrayDims': 1, 'ARROW_VERSION': '19.0.0'}
>>> ak.ones(10000, dtype=int)
array([1 1 1 ... 1 1 1])
>>> nums = ak.randint(0,500,10000, seed=1)
>>> ak.argsort(nums)
array([1984 2186 3574 ... 9298 9600 9651])
>>> ak.generate_history(num_commands=5, command_filter='ak.')
['ak.connect()', 'ak.get_config()', 'ak.ones(10000, dtype=int)', 'nums = ak.randint(0,500,10000)',
'ak.argsort(nums)']
arkouda.client.get_config() → Mapping[str, str | int | float][source]

Get runtime information about the server.

Returns:

Mapping containing selected server configuration and environment settings. Common keys include:

  • serverHostnamestr

    Hostname of the Arkouda server.

  • serverPortint

    Port number the server is listening on.

  • numLocalesint

    Number of Chapel locales (nodes) in the server deployment.

  • numPUsint

    Number of processor units (hardware threads) per locale.

  • maxTaskParint

    Maximum number of tasks per locale.

  • physicalMemoryint

    Total physical memory on each locale (bytes).

Return type:

Mapping[str, Union[str, int, float]]

Raises:

RuntimeError – If the client is not connected to a server.

arkouda.client.get_max_array_rank() → int[source]

Get the maximum pdarray rank the server was compiled to support.

Returns:

Maximum pdarray rank.

Return type:

int

arkouda.client.get_mem_avail(unit: str = 'b', as_percent: bool = False) → int[source]

Compute the amount of memory available to be used.

Parameters:

  • unit ({'b','kb','mb','gb','tb','pb'}) – Unit of the return value (default ‘b’).

  • as_percent (bool, default False) – If True, return the percentage of memory that is available.

Returns:

Amount of memory available (scaled per unit) or percentage if as_percent.

Return type:

int

Raises:

  • RuntimeError – Raised if there is a server-side error in getting memory used.

  • ValueError – Raised if the returned value is not an int-formatted string.

arkouda.client.get_mem_status() → List[Mapping[str, str | int | float]][source]

Retrieve the memory status for each locale.

Returns:

Each mapping contains:

  • total_memint

    Total physical memory on the locale host (bytes).

  • avail_memint

    Current available memory on the locale host (bytes).

  • arkouda_mem_allocint

    Memory allocated to the Arkouda Chapel process on the locale host (bytes).

  • pct_avail_memfloat

    Percentage of physical memory currently available on the locale host.

  • locale_idint

    Locale identifier (between 0 and numLocales - 1).

  • locale_hostnamestr

    Hostname of the locale.

Return type:

list of mapping

Raises:

  • RuntimeError – If there is a server-side error in retrieving memory status.

  • ValueError – If the returned data is not valid JSON.

arkouda.client.get_mem_used(unit: str = 'b', as_percent: bool = False) → int[source]

Compute the amount of memory used by objects in the server’s symbol table.

Parameters:

  • unit ({'b','kb','mb','gb','tb','pb'}) – Unit of the return value (default ‘b’).

  • as_percent (bool, default False) – If True, return the percentage of available memory that is used.

Returns:

Amount of memory used (scaled per unit) or percentage if as_percent.

Return type:

int

Raises:

  • RuntimeError – Raised if there is a server-side error in getting memory used.

  • ValueError – Raised if the returned value is not an int-formatted string.

arkouda.client.get_registration_config()[source]

Get the registration settings the server was built with.

Returns:

Snapshot of registration-config.json taken at server build time.

Return type:

dict

Raises:

RuntimeError – Raised if the client is not connected to a server

arkouda.client.get_server_commands() → Mapping[str, str][source]

Return a dictionary of available server commands and their functions.

Returns:

Mapping of command name → function (stringified).

Return type:

dict

Raises:

  • RuntimeError – Raised if there is a server-side error in retrieving and formatting the CommandMap

  • ValueError – Raised if there’s an error in parsing the JSON-formatted server string

arkouda.client.print_server_commands()[source]

Print the list of available server commands.

arkouda.client.ruok() → str[source]

Quick health check that does not require error handling.

Returns:

“imok” if the server is operating normally, otherwise an error string.

Return type:

str

arkouda.client.shutdown() → None[source]

Send a shutdown message and disconnect.

Performs:

  1. Delete all objects in the server SymTable.

  2. Shut down the server.

  3. Disconnect the client.

Raises:

RuntimeError – Raised if the client is not connected to the Arkouda server or there is an error in disconnecting from the server.