XCOMPUTE-CLIENT User Guide

XCOMPUTE-CLIENT User Guide#

If you haven’t already, download XCOMPUTE-CLIENT. After installation, you will receive an email containing your XCOMPUTE-CLIENT fingerprint. You can also view your fingerprints in your Account Profile.

1. Request Access#

Unless connecting as a read-only guest (e.g., testing xplicitcomputing.com), send your fingerprint and email address to the administrator of the server host you wish to access. Once approved, the admin will add your endpoint to the server’s users.cfg.

2. Launch & Login#

Starting the Application#

  • If installed via package manager, launch XCOMPUTE-CLIENT from your OS application menu.

  • Alternatively, run from terminal: xcompute-client or ./path/to/xcompute-client

Upon launch, client.cfg is loaded and the login window appears.

Login Process#

  1. Host Address: Enter the server’s DNS name (e.g., xplicitcomputing.com) or IPv4 address. If the server runs locally, use localhost.

  2. Port: The default service port is 11235. Leave blank to use the default.

  3. Credentials: Enter your email and fingerprint. This is only required once per device/account.

  4. Directories: Set default input and output paths for easy import/export operations. If unset, defaults to your home directory. Save the configuration.

Note: Update speed depends on network bandwidth and latency between client and server.

3. Interface Overview#

After successful login, interface.cfg is loaded for optional UX settings, and the main interface window appears as metadata and visuals buffer.

Configuration Example (interface.cfg)#

startingTab=0
dpi=100
panSensitivity=50
precision=3
rotateSensitivity=50
timeConstant=50
zoomSensitivity=50
groups=false
loops=false
surfaces=true
volumes=true

The main display window is powered by Qt5. After connecting to XCOMPUTE-SERVER, the client buffers and renders server-side systems. Closing the window terminates the client connection, but simulations continue running server-side. Teammates can reconnect or load from saved states.

4. File I/O#

Operation

Server Side

Client Side

Input

Load from host filesystem

Import from local machine

Output

Save to host filesystem

Export to local machine

Save & Load#

  • Save: Sends a command to the server to write system setup and state to the server’s output directory (e.g., fast SSD).

  • Load: Instructs the server to read files from its input directory. The client updates automatically once loaded.

  • No file I/O occurs on the client filesystem during Save/Load; these are server-side operations.

Import & Export#

All file types can be imported/exported to maintain a single source of truth. Files reside on the server alongside their associated systems.

Supported Neutral Formats:

  • Import: stl, obj, msh, sdf

  • Export: csv, vtu, stl, obj, msh, sdf

Native XC-Messages Formats:

  • xcs, xcg, xco (accessible via cross-language bindings)

External Application Integration#

Any file type can be associated with a shell command. By default, the OS uses open or xdg-open. Customize in extensions.cfg:

vtu=paraview --special-options
xcs=python3 -i path/to/concept_pb2.py
xcg=python3 -i path/to/spatial_pb2.py
xco=python3 -i path/to/vector_pb2.py
py=python3 -i path/to/concept_pb2.py path/to/vector_pb2.py path/to/spatial_pb2.py

Everything after = is executed as a shell command. No spaces are allowed around =, but spaces are permitted afterward.

5. Visualization & Rendering#

The render scene uses an OpenGL context with a shader pipeline.

Graphics Pipeline#

Current implementation uses an explicit raster pipeline with two programmable stages: vertex.glsl → fragment.glsl

VAO Layered Processing#

In-scene graphics are organized into Vertex Array Objects (VAOs) and rendered back-to-front:

  • Layer 0: 3D physical space (metaobjects & metaregions)

  • Layers 1+: 2D screen-space UX elements (HUD, text, tools)

Metaobjects & Interaction#

Most 3D objects are metaobjects composed of metaregions, representing server-side geometry. Transformations follow the standard M-V-P convention:

  • M Model: Assigned server-side for metaobjects, client-side for UX elements.

  • V View, P Projection: Managed client-side via the camera, optimized out for 2D.

Interaction:

  • Click to select metaregions in prep for server-side operations.

  • Double-click a metaregion to activate its parent metaobject.

  • Double-click the background to navigate up one hierarchy level.

  • Selection is currently limited to surfaces and faces.

Camera Controls#

  • Zoom: Middle mouse wheel or multi-touch swipe

  • Rotate: Hold middle mouse button, or Ctrl (Linux)

    • ⌘ + drag (macOS)

Press R to print render statistics to the console.

Shader Customization#

Advanced users can modify shaders/vertex.glsl and shaders/fragment.glsl. Press Ctrl+R (or Cmd+R on macOS) to dynamically reload shaders and the scene at runtime.

Context Menu & XC Command Bar#

  • Right-click: Opens a context-driven menu (options depend on active tab/selection).

  • XC Button: Enables a dynamic interpreter for manual/experimental commands.

    • test: Verify connectivity

    • refresh: Push latest metadata from server

    • reload: Load active system from server filesystem

    • load users.cfg: Update team roster on server

    • cd <system_name>: change directory

Experimental Feature: XC CLI is in dev and will be documented upon ratification.

6. Troubleshooting#

Failed Authentication#

Cause: Expired certificate, corrupt credentials, or unassigned MASH.
Fix:

  1. Clear keys/certs using the button in the Authentication Failure dialog.

  2. Unassign the fingerprint in your Account Profile.

  3. Relaunch the application to request new credentials from XWS.

Failed Login#

Click the Help button on the login screen. Diagnostic dialogs will display error details and suggested actions.

Runtime Errors#

Logs are stored in ~/.local/state/xcompute/xcclient/log/:

# View logs
ls -al ~/.local/state/xcompute/xcclient/log/xcclient-*.log
# View errors
ls -al ~/.local/state/xcompute/xcclient/log/xcclient-*.err
# Open with text editor
vi ~/.local/state/xcompute/xcclient/log/xcclient-VERSION.err