roboai-libs-client 0.1.11

Python client SDK for the RoboAI LIBS Spectrum Simulator API.

RoboAI LIBS Client

Lightweight Python client SDK and command-line helper for the RoboAI LIBS Spectrum Simulator API.

Contents

• Install
• Quick Start
• Authentication
• Usage Examples
• API Reference and Parameters
• Support
• License

Install

Prerequisite: Python 3.10 or newer.

From PyPI:

pip install --upgrade roboai-libs-client

From GitHub, if you need the latest repository version:

pip install git+https://github.com/RoboAI-Green/roboai-libs-client.git

Quick Start

Authenticate once:

roboai-libs auth login

Run a first static spectrum from Python:

from roboai_libs_client import RoboAILIBSClient

client = RoboAILIBSClient()

result = client.simulate_static(
    elements=["Ni"],
    range_min_nm=200,      # start wavelength in nm
    range_max_nm=230,      # end wavelength in nm
    resolution_nm=0.05,    # wavelength step in nm
    te_ev=1.0,             # electron temperature in eV
    ne_cm3=1e17,           # electron density in cm^-3
    fwhm_nm=0.0,           # instrumental FWHM in nm
)

print(result.wls[:5])
print(result.intensity[:5])

Or run the same kind of quick export from the command line:

roboai-libs static --element Ni --range 200 230 --resolution 0.05 --out ni.csv

For built-in command help:

roboai-libs --help
roboai-libs static --help
roboai-libs dynamic --help

Authentication

The client requires a platform Bearer token before calling protected simulation endpoints. The recommended setup is interactive login:

roboai-libs auth login

Enter your email address, open the verification link from your mailbox, and paste the returned access_token value. The token is stored locally, so future RoboAILIBSClient() calls can use it automatically.

Useful authentication and connection checks:

roboai-libs doctor
roboai-libs auth status
roboai-libs auth logout

roboai-libs auth status only checks local token configuration. roboai-libs doctor checks the API connection, validates the token if one is configured, and queries the elements endpoint.

Alternative authentication methods

Request a login email directly:

roboai-libs auth login --email [e-mail]

If you already have a token, validate it and store it locally:

roboai-libs auth login --token tok_...

Alternatively, pass a token directly with api_key=... or the ROBOAI_LIBS_API_KEY environment variable:

export ROBOAI_LIBS_API_KEY=tok_...

from roboai_libs_client import RoboAILIBSClient

client = RoboAILIBSClient(api_key="tok_...")

Usage Examples

1. List available elements

from roboai_libs_client import RoboAILIBSClient

client = RoboAILIBSClient()

elements = client.list_elements()
print(elements[:20])

Command-line equivalent:

roboai-libs elements

2. Static spectrum

from roboai_libs_client import RoboAILIBSClient

client = RoboAILIBSClient()

result = client.simulate_static(
    elements=["Ni"],
    range_min_nm=280,
    range_max_nm=330,
    resolution_nm=0.05,
    te_ev=1.0,
    ne_cm3=1e17,
)

print(len(result.wls), len(result.intensity))
print(result.lines[:3])

Command-line equivalent:

roboai-libs static --element Ni --range 280 330 --resolution 0.05 --out ni.csv

3. Mixture spectrum

proportions do not need to sum to 1. The client normalizes them before sending the request.

from roboai_libs_client import RoboAILIBSClient

client = RoboAILIBSClient()

result = client.simulate_static(
    elements=["Ni", "Fe"],
    proportions=[2, 1],
    range_min_nm=280,
    range_max_nm=330,
    resolution_nm=0.05,
    te_ev=1.0,
    ne_cm3=1e17,
)

print(result.wls[:5])
print(result.intensity[:5])

Command-line equivalent:

roboai-libs static \
  --element Ni \
  --element Fe \
  --proportion 2 \
  --proportion 1 \
  --out ni_fe.csv

4. Instrument broadening

from roboai_libs_client import RoboAILIBSClient

client = RoboAILIBSClient()

result = client.simulate_static(
    elements=["Ni"],
    range_min_nm=280,
    range_max_nm=330,
    resolution_nm=0.05,
    te_ev=1.0,
    ne_cm3=1e17,
    fwhm_nm=0.10,
    instrument_profile="gaussian",
)

print(result.instrument_profile, result.fwhm_nm)

5. Dynamic exposure

from roboai_libs_client import RoboAILIBSClient

client = RoboAILIBSClient()

result = client.simulate_exposure(
    elements=["Ni"],
    range_min_nm=200,
    range_max_nm=230,
    resolution_nm=0.05,
    te_ev=1.0,
    ne_cm3=1e17,
    fwhm_nm=0.0,
    integration_time_s=1e-6,
    time_resolution_s=100e-9,
)

print(len(result.time_vector))
print(len(result.snapshot_matrix), len(result.snapshot_matrix[0]))
print(len(result.total_exposure))

snapshot_matrix is the time-wavelength intensity matrix. total_exposure is the time-integrated spectrum.

6. Save dynamic HDF5

from roboai_libs_client import RoboAILIBSClient, ExposureRequest

client = RoboAILIBSClient()

request = ExposureRequest(
    elements=["Ni"],
    range_min_nm=200,
    range_max_nm=230,
    resolution_nm=0.05,
    integration_time_s=1e-6,
    time_resolution_s=100e-9,
)

path = client.save_dynamic_hdf5("ni_dynamic.h5", request)
print(f"Saved {path}")

Command-line equivalent:

roboai-libs dynamic --element Ni --out ni_dynamic.h5

The current platform API serves HDF5 for completed dynamic exposure jobs. Static spectra are available through simulate_static() as typed JSON results.

API Reference and Parameters

Main client methods:

• RoboAILIBSClient() creates a client using the stored login token or ROBOAI_LIBS_API_KEY.
• list_elements() returns element symbols available from the hosted simulator.
• simulate_static(...) returns a StaticSpectrumResult.
• simulate_exposure(...) returns an ExposureResult.
• save_dynamic_hdf5(path, request) submits a dynamic exposure job, waits for it, downloads the HDF5 result, and returns the written Path.

Most spectrum requests use the following parameters:

Parameter	Meaning
elements	Element symbols to include, for example ["Ni"] or ["Ni", "Fe"].
proportions	Relative element proportions. Values are normalized automatically, so [2, 1] becomes 2/3 and 1/3.
range_min_nm	Start wavelength of the simulated range, in nanometres.
range_max_nm	End wavelength of the simulated range, in nanometres.
resolution_nm	Wavelength spacing, in nanometres. Smaller values give finer spectra but require more computation.
te_ev	Electron temperature in electronvolts.
ne_cm3	Electron number density in cm^-3.
fwhm_nm	Instrumental broadening full width at half maximum, in nanometres. Use 0.0 for no instrumental broadening.
instrument_profile	Instrument broadening profile, usually "gaussian" or "lorentzian".
integration_time_s	Total simulated exposure time for dynamic simulations, in seconds.
time_resolution_s	Time step for dynamic simulations, in seconds.

Typed request models:

• StaticSpectrumRequest
• ExposureRequest
• PlasmaConfig
• TemporalConfig

Typed result models:

• StaticSpectrumResult
• ExposureResult

Support

For bugs, questions, or feature requests, please open an issue on the GitHub repository.

License

MIT License.