XCOMPUTE-SERVER

XCOMPUTE-SERVER#

1. Configure#

Several config files are ingested upon program launch.

1a. Project#

Up to two system administrators can be defined in server.cfg. The first admin must be the email associated with the fingerprint in use, while the second admin can be any trusted user’s email with matching XCOMPUTE-CLIENT credentials.

For example, a typical server configuration may look like:

admin=me@mycompany.com         # your registered email address (required) 
fingerprint=YOUR_XCSERVER_FINGERPRINT # your assigned fingerprint (required)
input=/mnt/FAST_SSD/            # load directory for project (usually the same as output)
output=/mnt/FAST_SSD/           # save directory for project (usually the same as input)
cache=/mnt/FAST_SSD/_cache/     # a place to put temporary files (okay to be within input/output provided _underscore)

Depending on your setup, you may wish to specify an independent drive for the cache:

cache=/mnt/ANOTHER_FAST_SSD/cache/  # another mount point provides enhanced isolation and performance

It is recommended that trusted admins be proficient in Linux/Unix environments. Questions about adminstration should be directed to Xplicit Computing by the customer admin on file.

1b. User Access#

To manage team access, edit users.cfg and enter the fingerprints and emails (as provided by team members):

allow_guests=false
SOMEONES_XCCLIENT_FINGERPRINT=someone@somewhere.com
ANOTHERS_XCCLIENT_FINGERPRINT=helper@subcontractor.com
...

Set allow_guests=true to permit others (the public, with authenticated XCOMPUTE-CLIENT) to access your project/simulation (with read-only permissions and no file exports). If unspecified, the default is allow_guests=false.

1c. Host Collaborators#

To manage host connectivity, edit hosts.cfg to allow auto-discovery on LAN; specify any collaborating servers:

localnet=192.168.1 					# optional, should be commented out if not used (takes a minute to search all addresses)
CLUSTER_XCSERVER_FINGERPRINT=192.168.1.2		# a local cluster's address
ANOTHER_XCSERVER_FINGERPRINT=anothercompany.com		# some other domain hosting a public server (or an IP address)
...

An optional localnet entry sets a class-C subnet range to automatically scan for available XCOMPUTE-SERVER connections (between .2 and .254). In all cases, local and wide-area network IP and DNS names are resolved.

Note: the server-server protocol and load distribution are a work-in-progress. Upcoming xcserver releases will take advantage of this functionality.

1d. Compute Defaults#

To manage compute defaults, edit compute.cfg. A few important params include:

ReservedThreads=1       # number of reserved CPU threads (to keep server responsive)
DefaultDevice=0         # 0: let application pick best default
Iterations=500          # default number of steps in iterative methods
Resolution=16000000     # shape resolution is typically between 1e6 and 1e8
ElementCount=40000      # default node or cell count for new meshes
...

2. Execution#

  • As with most services, XCOMPUTE-SERVER requires adminstrator (root) privilege.

  • Before shutdown, save your project via XCOMPUTE-CLIENT so the session can be recalled from storage.

2a. System-managed service#

XCOMPUTE-SERVER can be managed as a service that starts or restarts when the host system boots up, and is shut down when the system is shut down, similar to Apache2 and other persistent host services.

For Ubuntu and Debian systems, the Debian (.deb) package in recommended. Like other Debian packages, adminstrator (root) privilege is required for installation. A new user xcompute is created to run XCOMPUTE-SERVER and manage team projects files. Following setup and restart, the service is managed by Linux systemd.

As an installed Ubuntu/Debian package, XCOMPUTE runs as a service under the management of systemd via the systemctl command. Checking the status of the service can be done without admin privilege:

Check the systemd service status:

systemctl status xcompute

The output should show Active: active (running):

$ systemctl status xcompute
● xcompute.service - XCOMPUTE Service
     Loaded: loaded (/etc/systemd/system/xcompute.service; linked; vendor preset: enabled)
     Active: active (running) since Sat 2025-03-29 18:32:35 PDT; 18min ago
   Main PID: 233561 (xcompute-server)
      Tasks: 13 (limit: 18988)
     Memory: 21.4M
     CGroup: /system.slice/xcompute.service
             └─233561 /opt/xcompute/xcserver/bin/xcompute-server

The active xcompute-server process will write messages to logfiles in /var/opt/xcompute/xcserver/log.

Nominal logs are written to xcserver.log, error messages to xcserver.err.

If running, xcserver.log will show the software version (e.g., 25.1-...), license certificate loading, launching XCOMPUTE-SERVER, and CPU and OpenCL resources that are available. For example, the last few lines of the start-up may include:

Model name:                           Intel(R) Core(TM) i9-9900 CPU @ 3.10GHz
CPU(s):                               16
NUMA node0 CPU(s):                    0-15
...
compute platform: NVIDIA CUDA
OpenCL 3.0 CUDA 12.4.131 (FULL_PROFILE)
...

If the service fails, the error file is a good place to look for clues. For example:

$ cd var/opt/xcompute/xcserver/log
$ tail xcserver.err
Cannot authenticate without a fingerprint. Aborting.
Authentication Failed.
A valid certificate is required to launch xcompute-server...
See https://xplicitcomputing.com/help.html for details

To manually start the service:

sudo systemctl start xcompute

The service can also be stopped:

sudo systemctl stop xcompute

Or restarted:

sudo systemctl restart xcompute

Note: start and restart subcommands produces no messages. To check success, use the status subcommand.

2b. User-managed service#

XCOMPUTE-SERVER can be run manually as an individual user application. No adminstrator (root) privilege is required as the software is installed in a user-owned directory. XCOMPUTE-SERVER runs as process owned by the user, and thus all data files consumed or generated by XCOMPUTE-SERVER are under control of the user. This is most suitable for individual use and where root privilege is not readily available.

Navigate to the executable working directory and start an interactive session:

./xcompute-server

Ensure the listening socket has been bound and at least one OpenCL device is available. Only one xcompute-server instance is permitted, so don’t attempt to run as a user if a systemd xcompute service is also running.

3. File I/O#

Client interfaces import/export external files to/from the server, while the server host saves/loads native XC files locally:

Input

Output

Server

Load from host

Save to host

Client

Import from remote

Export to remote

On the server side, save operations write to the output directory, while load operations read from the input directory. A third cache location is used to store temporary runtime files.

3a. Save & Load#

XCOMPUTE-SERVER saves the project state to the output directory and loads from the input directory, all on the host machine. The project input/output directories should be specified in server.cfg, such as a dedicated fast SSD:

input=/path/to/project/
output=/path/to/project/

Project files are organized in a filesystem hierarchy with the definition (XCS/JSON) and supporting files for each system within each folder. In this manner, each system maps to a folder and its contents.

*.xcs/*.json - system setup

  • Both XCS and JSON files are saved; the previous state is saved as a backup with the . prefix to make them hidden. This approach provides effecitvely triple-rundundancy for each system’s setup with both human- and machine- centric approaches.

  • Upon load, it first tries to load the JSON before the XCS (permitting easy customization of the JSON setups).
    A couple other native types are present in each system’s directory:

*.xcg - geometry
*.xco - data

  • Imported and generated geometries are saved in a native *.xcg file.

  • Data properties are saved to *.xco files for performant storage and access. A standalone app xc2csv is provided to view data files in a spreadsheet format. The XC-Messages example “Hello Vector” also demonstrates how to access *.xco files.

3b. Import & Export#

When a server imports one or more files, as they are received they are staged in the cache directory. From there, they are read and/or copied into the respective system directory. A similar reverse process is used for exporting. These procedures are implemented to assure that import/export operations are segregated from the coveted project files (as to prevent pollution and corruption).

XCOMPUTE-SERVER can import recognized file formats, including:

stl, obj, msh, sdf

XCOMPUTE-SERVER can also export certain file formats, including:

csv, vtu, stl, obj, msh, sdf

The default export types for geometries and systems can be defined in compute.cfg, such as the defaults:

SystemExportType=vtu
GeometryExportType=msh

4. Troubleshooting#

Detailed information is available in the application message and error logs.

View the log files: vi /var/opt/xcompute/xcserver/log/xcserver.log

View the error/warning files: vi /var/opt/xcompute/xcserver/log/xcserver.err