1 Background and Motivation

Existing desktop pet applications mostly loop predefined animations, and interaction with the user is limited to clicks that trigger fixed motions; LLM chat tools, on the other hand, exist as separate windows and require a context switch to use. The design goal of DeskPet is to combine the two:

• Persistent yet unobtrusive: the character window is transparent; only the opaque pixels of the character itself respond to the mouse, and clicks on all other regions pass through to the windows below;
• Consistent language and motion: the model supplies both the line of dialogue and a motion tag in the same reply, so the character’s expression, motion and tone of speech remain consistent;
• Oriented towards research workflows: the same character can switch to a research mode in which answers are rendered in Markdown and LaTeX and retrieval tools such as arXiv and Semantic Scholar can be invoked;
• Lightweight build: the only dependency is the Xcode Command Line Tools (swiftc); no Xcode project is used.

2 Feature Overview

Figure 1 DeskPet running on the macOS desktop (screenshot from a running instance, 2026-10-14). The character is Tororo, named “墨笃” (Modu); the model service is DeepSeek (deepseek-flash, OpenAI-compatible endpoint). The bubble above the head is the model’s reply to “I have to revise a paper this afternoon; remind me to get up and move in half an hour”. The remind field of the same reply created a reminder 30 min later, and the motion field triggered a paw-licking motion; the chat input box is at the bottom.

3 User Interface

3.1 Chat

Clicking the character’s body or pressing ⌥Space opens the chat input box. User messages and character replies are both stacked as bubbles above the head, and when a reply arrives the character simultaneously plays the motion selected by the model.

Figure 2 Three frames of a single conversation (screenshots from a running instance; times measured from the moment Send was clicked). Left: typing the message; middle: at 1.5 s, the user message is shown in a purple bubble at the top, the reply has begun streaming into the bubble below, and the character is playing a motion; right: at 7.5 s, the reply is fully displayed, and the earlier user bubble has moved up with reduced opacity.

In the JSON returned by the model, reply is displayed as a bubble, motion is mapped to a Live2D motion via pet-map.json, and remind is passed to the reminder scheduler; all three are completed within a single request, without a separate intent-recognition step.

3.2 Menu-Bar Menu and Context Menu

The menu-bar icon (a paw print) and the character’s context menu are generated by the same function, addItems(to:), and contain identical items: Chat, Research mode, Run daily tasks, Messages, Focus for 25 minutes, Reminders, Settings, Window layer, and others. When research mode is on, “New research topic” and “Search the web (slower)” additionally appear, and “Hop somewhere else” is hidden. On displays with a notch the menu-bar icon may be obscured, so the context menu retains all entries.

Figure 3 Menu-bar menu with research mode on (screenshot from a running instance).

The window layer offers three options:

3.3 Research Mode

Research mode is a state of the character; when it is on, questions entered in the input box are answered by the research assistant. The answer bubble supports Markdown, KaTeX formulae and code highlighting and is scrollable; clicking the bubble opens the full conversation window.

Figure 4 Answer bubble in research mode (screenshot from a running instance). The question was “Briefly explain the composition of the loss function when a PINN solves the Biot consolidation problem, and give the formulae”, with web retrieval disabled. At 12 s after sending, the bubble still showed “Thinking.”; at 18 s the complete answer was displayed. Inside the bubble, KaTeX renders the residual term $\mathcal{L}_r$, the boundary term $\mathcal{L}_b$ and the initial term $\mathcal{L}_0$; the content is scrollable when it exceeds the bubble height, the “×” at the top right closes it immediately, and the input box at the bottom indicates that research mode is active.

Figure 5 Messages window (screenshot from a running instance). The left column groups conversations into “Daily chat” and “Research chat”, showing the title, time and message count, and includes the “Daily Briefing” generated by the daily tasks; the right column shows the full record of the conversation in Figure 4, with the model used noted beside the title. The conversation can be renamed, deleted or continued, and “Search literature online” can be ticked.

3.4 Settings

The Settings window is divided into six tabs: General, About me, Model, Reminders, Daily tasks and Memory. Figure 6 shows four of them; “About me” and “Memory” contain personal information and are not shown.

Figure 6 Settings window (screenshots from a running instance). Top left: the General tab, containing the name, form of address, persona and character selection, with the copyright notice required by the model shown below the character; top right: the Model tab, which switches between Claude (Anthropic) and OpenAI-compatible endpoints, with the API key displayed masked and stored in the Keychain; bottom left: the Reminders tab, containing meal, work start/end, prolonged-sitting and drinking-water reminders; bottom right: the Daily tasks tab, with one task per line and an option to run them once immediately.

4 System Architecture

The source code comprises 27 Swift files (5 192 lines) and 7 front-end files (1 428 lines), compiled by build.sh invoking swiftc directly, without a Swift Package or an Xcode project. The code is organised in three layers:

The data flow is as follows:

User input (input box / ⌥Space) ─▶ PetBrain ──┬─ System prompt: persona + user info + memory store + reply format                                              ├─ Context: current time + local weather (cached 30 min)                                              ▼                                  LLMProvider (Anthropic / OpenAI-compatible, SSE streaming)                                              ▼                                  PetReply.parse ─▶ reply   → bubble (pet.js)                                                  ├─ motion  → pet-map.json → Live2D motion group / expression                                                  ├─ remind  → ReminderScheduler                                                  ├─ weather_city → fetch weather, then request again                                                  └─ remember / forget → MemoryStore

Character rendering and bubbles reside in a WKWebView, and the native layer and web layer communicate bidirectionally via WKScriptMessageHandler and evaluateJavaScript. The native layer is responsible for the window, mouse pass-through, gaze coordinates, reminders and model calls; the web layer is responsible for Live2D drawing, hit testing and bubble layout.

5 Key Implementation Details

5.1 Structured Replies

Pet conversations require the model to output a single JSON object, whose JSON Schema is given by PetReply.schema, with additionalProperties: false set on all objects. motion is drawn from 11 semantic motions: idle, happy, wave, nod, shake, think, surprised, sleepy, shy, eat and sad. Claude guarantees the format through structured outputs; OpenAI-compatible endpoints use JSON mode.

The parser adopts a fault-tolerant strategy towards the model output: it attempts, in order, the entire text, the text inside a Markdown code block, and the substring between the first { and the last }; unknown motion names fall back to idle; if all attempts fail, the entire text is used as the dialogue line. This strategy makes models that do not support strict structured output (such as some OpenAI-compatible services) equally usable.

5.2 Mapping Semantic Motions to Model Motions

Different Live2D models name their motion groups and expressions differently. The pet-map.json in each model directory maps the 11 semantic motions to that model’s motion group (group), index within the group (index) and expression (expression); an entry may contain params, which smoothly override model parameters for the duration of the motion and serve for expressions the model does not provide. Taking shake of the sample model Tororo as an example:

"shake": {  "group": "Idle", "index": 1,  "params": { "PARAM_EAR_L": -0.7, "PARAM_EAR_R": -0.7, "PARAM_TAIL_ANGRY": 1 }}

This entry plays an idle motion while lowering both ears and setting the tail to an angry pose. While speaking, the application sets the parameters of the LipSync group frame by frame (default ParamMouthOpenY) to drive the mouth shape.

5.3 Click-Through on Transparent Regions

On macOS, ignoresMouseEvents of an NSPanel can only be set for the window as a whole and cannot distinguish individual pixels. DeskPet adopts a “web-side sampling + native-side query” approach:

1. Every 200 ms, the web side draws the WebGL canvas (preserveDrawingBuffer: true) at reduced scale onto a probe canvas and reads the alpha channel in units of 10 × 10 CSS pixels; units with alpha > 24 are marked solid, and the resulting bitmap is passed to the native layer through the message channel;
2. The native layer reads the pointer position at 30 Hz, converts it to page coordinates and queries the bitmap; when the pointer lies on a solid unit the window receives mouse events, otherwise the events pass through.

The same timer passes the pointer coordinates to the web side to drive the character’s gaze tracking.

5.4 Following the Music Beat

The music rhythm feature consists of two steps, playback detection and beat estimation:

• Playback detection: every 0.5 s, Core Audio process objects are queried to determine whether other applications are outputting audio; this query requires no authorisation. Output lasting ≥ 1.5 s is regarded as the start of playback (to exclude notification sounds), and silence lasting ≥ 2 s is regarded as a stop;
• Beat estimation: on macOS 14.2 and later, system audio is obtained through a Core Audio process tap (requiring the “System Audio Recording” permission); the energy envelope of the low-pass band at approximately 150 Hz is computed and onsets are detected, the tempo is estimated from the median of the inter-beat intervals, and the character is driven to sway from side to side at half-beat tempo. Without the permission, a fixed rhythm of approximately 112 BPM is used instead.

Audio is analysed in real time on the local machine only; it is not recorded, stored or uploaded.

5.5 Memory Store

Long-lived information that appears in conversation (preferences, allergies, important dates, long-term plans, etc.) is written by the model via the remember field, and the interface indicates this with a “📝 Noted” bubble; the forget field deletes entries by keyword. Entries are appended, from newest to oldest, to the system prompts of small talk, research and daily tasks, up to a limit of 2 400 characters. The deduplication rules are as follows:

5.6 Tool Loop in Research Mode

The research engine calls the model at most 3 times per turn: the first 2 calls permit tool use, and the 3rd prohibits tools and forces an answer. All tool calls in the same round are executed in parallel, and their results are merged into a single message returned to the model. The available client-side tools are as follows:

Stability measures: a single request times out after 12 s; HTTP 429 / 503 is retried only once, after which requests to the same host return an error directly for 60 s so that the model switches to another source; identical searches within 10 min reuse the cache. When Claude is used, the server-side web_search can additionally be invoked; Claude’s assistant messages are saved as raw content blocks and returned verbatim, keeping the conversation history append-only to benefit prompt caching.

Some OpenAI-compatible models (such as DeepSeek) occasionally write tool calls into the body text using their native markup. The application hides such markup in the streaming output and parses it into tool calls for execution.

5.7 Weather-Change Alerts

Based on the city in “About me”, the hourly forecast is fetched every 20 min and compared with the current weather:

6 Model Services

API keys are stored in the macOS Keychain (service local.deskpet) and are never written to disk or UserDefaults in plain text.

7 Build and Installation

7.1 Build

macOS 14 or later (14.2 or later for beat following) and the Xcode Command Line Tools are required:

git clone https://github.com/Yu-Xiang-Yang/deskpet.gitcd deskpet./build.sh install

On the first build, scripts/fetch-vendor.sh downloads pinned versions of the front-end libraries (pixi.js 6.5.10, pixi-live2d-display 0.4.0, marked 12.0.2, DOMPurify 3.1.6, KaTeX 0.16.11, highlight.js 11.10.0) and verifies the SHA-256 of each; no CDN is accessed at run time.

When no signing certificate is configured, the application is signed ad hoc; the signature changes with every rebuild, and the system requests the Keychain and “System Audio Recording” permissions again. After a self-signed code-signing certificate named DeskPet Code Signing is created in Keychain Access, build.sh signs with it and the permissions remain valid across rebuilds.

7.2 Live2D Components

Redistribution of both Live2D Cubism Core and the sample models is prohibited, so the repository contains no Live2D files. Users must download the Cubism SDK for Web and the Tororo & Hijiki sample models from the official Live2D website themselves, and then run:

scripts/install-live2d.sh ~/Downloads/CubismSdkForWeb-5-r.5.zip ~/Downloads/tororo_hijiki_ja.zip

The script copies Cubism Core and the two models into ~/Library/Application Support/DeskPet/models/ and adds the corresponding pet-map.json. The drawing-order interface changed starting with Cubism Core 5.1; pet.js registers a compatibility mapping after loading Core, which allows pixi-live2d-display 0.4.0 to work with Cubism SDK for Web 5-r.5 (Core 6.0.1).

8 Testing

9 Data Storage and Network Access

The application accesses only the API address of the selected model service, the data sources of the retrieval tools listed above, and public web pages specified by the model via fetch_webpage.

10 Design Trade-offs

11 Limitations and Caveats

• The Live2D components must be obtained by users themselves; before publicly distributing a prebuilt application that can load arbitrary models, the Live2D publication licence terms must be confirmed (such an application may fall under the “expandable application” category);
• Under ad-hoc signing, the Keychain and System Audio Recording permissions must be granted again after every rebuild;
• News and market data rely on unofficial endpoints and may stop working when the providers make changes;
• Under the “Desktop only” layer, the bubbles are covered by application windows, and reminders are visible only as system notifications.

12 Project Repository

GitHub: https://github.com/Yu-Xiang-Yang/deskpet (MIT License, with Chinese and English READMEs and third-party licence notices).

The screenshots in this article use the Live2D sample model Tororo. This content uses sample data owned and copyrighted by Live2D Inc. Live2D and Cubism are trademarks or registered trademarks of Live2D Inc.; this project is not affiliated with Live2D Inc.

1 Background and Motivation

When working with Claude Code, the user needs to know the state of the current quota window: how much of the 5-hour window remains, how much of the weekly quota has been consumed, and when each resets. Obtaining this information is inconvenient in three respects:

• Visibility: the quota percentages and reset times appear only on the usage page, so reading them requires leaving the current working window;
• Separated data sources: the quota percentages are computed server-side and are absent from local logs, whereas token counts and costs can be derived only from local logs. The two kinds of data must be obtained separately and then merged for display;
• Non-recoverable history: Claude Code purges old session logs, so long-term usage trends cannot be preserved from the logs alone; the widget must store its own daily aggregates.

The aim of Claude Usage Widget is to merge these data into a single card that resides on the desktop, with an appearance and interaction model that follow the conventions of system widgets.

2 Feature Overview

Figure 1 Extra-large size (704 × 344 pt) interface (simulated data rendered in --demo mode; it does not correspond to a real account). The left column shows the 5-hour, weekly and per-model (Fable) weekly quotas, each accompanied by the local token count and estimated cost within that window; the right column shows the daily token heatmap (107 active days in the last 21 weeks), the today / last 7 days / last 30 days summaries, today’s token composition and the model shares.

The main features are as follows:

In the simulated data of Figure 1, today’s total is 214.0 M tokens, of which cache reads account for 203.5 M (95.1 %) and output for 820.0 K (0.38 %). This composition indicates that the total token count is dominated by cache reads. According to the price table in the source code, the cache-read unit price of Opus 5.5 is 5 % of the input price (0.20 / 4); the total token count is therefore not proportional to the estimated cost, and the widget displays both side by side.

3 Sizes and Interface

3.1 Widget Sizes

Figure 2 The four sizes (simulated data).

Figure 3 Light and dark appearances of the large size (simulated data).

Figure 4 Small size (left) and medium size (right) (simulated data).

3.2 Application Icon

Figure 5 Application icon (512 × 512 px).

The icon is drawn from geometric primitives by scripts/make-icon.swift and contains no third-party or brand assets: on a dark rounded square, an orange ring represents the usage gauge, with a four-pointed star inside the ring. The icon is displayed in Finder, Launchpad, Spotlight and the Login Items list. The icon resides in the main branch (Resources/AppIcon.icns, written into the app bundle by build.sh); the changelog lists it as an addition in 1.0.1, which has not yet been released, so the v1.0.0 release package does not contain it.

4 System Architecture

The complete source of v1.0.0 consists of 9 Swift files totalling 2 389 lines, compiled together by build.sh, without a Swift Package or an Xcode project. The data flow is as follows:

Claude Code logs (*.jsonl) ─▶ UsageScanner (incremental scan every 30 s, per-message dedup)                                   │                                   └─▶ HistoryStore (daily aggregates, history.json) ─┐                                                                                      ├─▶ Snapshot ─▶ WidgetView (SwiftUI, four sizes)claude.ai usage endpoint ─▶ QuotaFetcher (embedded WebKit, at most once per minute) ─▶ QuotaInfo ─┘                                                    └─ quota.json (shown immediately after restart)

Snapshot serves as the interface between collection and presentation: log scanning and quota retrieval each complete in the background, and their results are merged and published to the view layer. A failure in quota retrieval does not affect the updating of local statistics or the heatmap.

5 Local Usage Statistics

The widget reads the Claude Code session logs (~/.claude/projects/**/*.jsonl, together with ~/.config/claude/projects and the directory specified by CLAUDE_CONFIG_DIR) and accumulates the usage field of each assistant message.

5.1 Definition of Tokens

The total token count is defined as the sum of four terms: input, output, cache write and cache read. Cache writes are recorded separately for the 5-minute and 1-hour TTLs in cache_creation; when the sum of the two is smaller than cache_creation_input_tokens, the difference is attributed to the 5-minute TTL. Records whose model identifier is <synthetic> are excluded.

5.2 Deduplication of Streamed Messages

A single streamed message is written to the log multiple times, with the output token count of successive records increasing as generation proceeds. The widget uses the combination of message.id and requestId as a key and retains, for each key, only the record with the largest output token count (the final entry). When both the message and request identifiers are missing, the record’s uuid is used instead. Measurements show that without deduplication the total token count is approximately doubled.

5.3 Cost Estimation

Costs are estimated from published API list prices. The price table is Pricing in the source code (Sources/UsageStore.swift), in US dollars per million tokens, matched by the longest prefix of the model identifier; unmatched models are priced as claude-opus-5-5. The cost of a single record is

$$ C = 10^{-6} \left( p_{\mathrm{in}} N_{\mathrm{in}} + p_{\mathrm{out}} N_{\mathrm{out}} + 1.25 \cdot p_{\mathrm{in}} N_{\mathrm{w5m}} + 2 \cdot p_{\mathrm{in}} N_{\mathrm{w1h}} + p_{\mathrm{cr}} N_{\mathrm{cr}} \right) $$

where $N_{\mathrm{in}}$, $N_{\mathrm{out}}$, $N_{\mathrm{w5m}}$, $N_{\mathrm{w1h}}$ and $N_{\mathrm{cr}}$ are the token counts of input, output, 5-minute cache write, 1-hour cache write and cache read respectively, and $p_{\mathrm{in}}$, $p_{\mathrm{out}}$ and $p_{\mathrm{cr}}$ are the corresponding input, output and cache-read prices. Cache writes are charged at 1.25 times (5-minute TTL) or 2 times (1-hour TTL) the input price. Subscription plans are not billed per token, so this value serves only for relative comparison; the price table must be updated manually when prices change.

5.4 Scanning Overhead

The logs are scanned incrementally every 30 s; the initial full scan of 700 MB of logs takes approximately 2 s. The statistics cover only the local Claude Code; conversations in the claude.ai web interface and usage on other devices are not included.

5.5 Heatmap

The heatmap has one cell per day, with Monday as the first day of the week, and its metric is either tokens or message count. There are 5 colour levels: days with no recorded usage take the lightest level, and the boundaries of the remaining 4 levels are the 25 %, 50 % and 75 % quantiles of the active days. Daily aggregates are stored in history.json, so the recorded history is retained after Claude Code purges old session logs.

6 Retrieval of Subscription Quotas

The quota percentages are computed server-side and are absent from local logs. The widget therefore uses the same data as the claude.ai usage page, retrieved as follows:

1. The sign-in window is an embedded WebKit view, and the sign-in state is stored in the widget’s own WebKit data store;
2. At most once per minute, the widget loads /api/organizations/<org_id>/usage within that store. The limits list in the response contains three window types, session (5 hours), weekly_all and weekly_scoped (per model), each with a percentage and a reset time; the legacy fields five_hour and seven_day serve as fallbacks;
3. The parsed result is cached in quota.json and shown immediately after a restart.

This endpoint is not a public API. When the endpoint changes or the sign-in expires, the widget falls back to a 5-hour window estimated from local logs and displays the reason, rather than a fabricated percentage.

6.1 The Passkey Issue in the Sign-In Window

A locally built application lacks the passkey entitlement held by browser-class applications. When the sign-in page detects that WebAuthn is available, it offers a passkey first, after which the flow stalls. The widget injects a script into the sign-in window before the document loads, handled as follows:

With WebAuthn blocked, Google and claude.ai fall back to password, device confirmation or an email verification code. Google and Apple sign-in take place in pop-up windows, and the sign-in window has been permitted to open windows via script. Sign-in links in emails open in the default browser and the resulting sign-in state does not reach the widget; the verification code should be used instead.

6.2 Credentials and Network Scope

• The widget does not read, copy or transmit passwords, cookies or tokens; it reads only the response of the usage endpoint;
• The only network destination is claude.ai;
• “Clear Sign-In” in the context menu deletes the WebKit data, the saved organisation identifier and quota.json.

Because the endpoint is not public, its use should be checked against Anthropic’s Terms of Service in advance.

6.3 Stored Files

7 Reproducing the Geometry of System Widgets

System widgets are WidgetKit extensions that must be signed with a developer certificate, and building them requires the full Xcode. This project does not use WidgetKit; the widget is therefore an independent borderless panel and does not appear in the system widget gallery. Its geometric parameters are taken from measurements of system widgets on macOS 26, obtained through the window list.

The card side lengths above satisfy $180n - 16$ ($n$ being the number of grid cells occupied): for $n = 1, 2$ they are 164 and 344 pt respectively. The extra-large size is derived from the same grid, with width at $n = 4$, giving 704 pt, and height at $n = 2$, giving 344 pt; this size has not been measured.

The window behaviour is as follows:

• Snapping: during dragging the panel snaps to the screen margins, the screen centre lines and the 180 pt grid lines, with a threshold of 14 pt, and always remains within the screen; it is likewise placed on the grid at launch and after a size change;
• Level: the panel lies above the desktop icons and below ordinary windows, is visible in all Spaces, and is covered by maximised windows; enabling “Keep on Top” changes this behaviour;
• Shadow: no drop shadow is drawn, consistent with system widgets on the desktop.

8 Installation and Usage

8.1 Installation

Option 1: release package (recommended). Download ClaudeUsageWidget-<version>-macos.zip from the latest release page (universal binary supporting Apple silicon and Intel, requiring macOS 14 or later), extract it, and move ClaudeUsageWidget.app into /Applications. The application is ad-hoc signed and not notarised, so the system blocks the first launch; run the following command once to remove the quarantine attribute:

xattr -dr com.apple.quarantine /Applications/ClaudeUsageWidget.app

Alternatively, choose “Open Anyway” in “System Settings → Privacy & Security”. The release page provides SHA256SUMS.txt for verifying the downloaded files.

Option 2: build from source. Only the Xcode Command Line Tools (xcode-select --install) are required, not the full Xcode:

git clone https://github.com/Yu-Xiang-Yang/claude-usage-widget.gitcd claude-usage-widget./build.sh install          # build and install into /Applications (into ~/Applications when not writable)open /Applications/ClaudeUsageWidget.app

Running ./build.sh alone only produces build/ClaudeUsageWidget.app. The default SDK of the Command Line Tools may be newer than the installed compiler (error this SDK is not supported by the compiler); the script therefore prefers the macOS 26 SDK when it is present.

8.2 First Use

1. Right-click the widget, choose “Sign In to claude.ai…”, and sign in within the window that opens; the window closes automatically once the quota has been read.
2. “Launch at Login” can be enabled from the same menu; it must be re-enabled after the application is moved.

When not signed in, the widget shows a 5-hour window estimated from local logs together with a “Sign In” button; the heatmap and local statistics do not depend on sign-in. The quotas require a Claude Pro or Max subscription and a claude.ai sign-in; the local statistics and heatmap require Claude Code.

8.3 Command-Line Modes

9 Build, Verification and Release

The project currently has no test suite; verification relies on the command-line modes:

Continuous integration comprises two GitHub Actions workflows, both running on the macos-26 image (the Liquid Glass material requires the macOS 26 SDK):

10 Design Trade-offs

11 Limitations and Caveats

• The local statistics cover only the local Claude Code and exclude conversations in the claude.ai web interface and usage on other devices;
• The subscription quotas depend on an undocumented web endpoint and a valid sign-in state; the endpoint may change or cease to work;
• The extra-large size is derived from the system grid and has not been measured;
• When menu-bar space is insufficient (e.g. on displays with a notch), the system may hide the menu-bar icon; all functions remain available from the widget’s context menu;
• The price table must be updated manually when prices change;
• The widget does not appear in the system widget gallery and is covered by maximised windows (“Keep on Top” can be enabled).

12 Disclaimer and Project Repository

This project is independent and is not affiliated with, endorsed by or sponsored by Anthropic; “Claude” is a trademark of Anthropic. The project was developed with the assistance of Claude Code.

GitHub: https://github.com/Yu-Xiang-Yang/claude-usage-widget (MIT License, with Chinese and English READMEs, a changelog and a security policy).

1 Background and Motivation

GPU clusters typically organise resources by partition, and partitions differ substantially in GPU model, node count and load. Before submitting a job, the following three questions must be answered:

• which partitions still have idle GPUs;
• the maximum number of idle GPUs on a single node, which determines whether a multi-GPU job can start immediately;
• the elapsed run time, time limit and queue status of the user’s own jobs.

For clusters accessed through a VPN, the conventional procedure for obtaining this information is inconvenient in three respects:

• Lengthy procedure: the three steps of VPN connection, SSH login and command execution must be completed in sequence and repeated for every query;
• Raw output lacks aggregate values: scontrol show node prints one line per node, with the total GPU count in the Gres field and the allocated count in the AllocTRES field, which must be parsed and summed;
• Node states must be filtered: nodes in states such as DOWN and DRAIN cannot be scheduled, and counting them in the total overestimates the available resources.

The aim of Slurm GPU Widget is to automate this procedure and present the results in a persistent interface, so that the resource state can be read without logging in to the cluster.

2 Feature Overview

Figure 1 Übersicht desktop card interface (simulated data, rendered from the repository’s mock/ data and front-end source with SHOW_MY_JOBS=1 and JOB_GPU_USAGE=1 enabled). The upper part shows, for each partition, the numbers of running, pending and own jobs, GPU and memory occupancy bars, and the maximum number of idle GPUs on a single node; the lower part, “My jobs”, lists the job ID, name, elapsed time / time limit, and the memory usage and utilisation of each GPU.

The main features are as follows:

3 System Architecture

The project consists of one collection script and two front ends; the data flow is as follows:

Tunnelblick (VPN state detection / automatic connection)        │        ▼cluster-status.sh ── ssh (BatchMode, ControlMaster) ──▶ login node: scontrol / squeue        │  local awk aggregation        ├──── JSON ─────────────▶ Übersicht desktop card        └──── --swiftbar-stream ▶ SwiftBar menu bar

Both front ends call the same collection script, cluster-status.sh, and they can be installed individually or together. The collection script supports four invocation modes:

The JSON structure is the interface contract between the collection layer and the presentation layer; replacing either side does not affect the other.

4 Data Collection Method

The collection procedure comprises five steps:

1. VPN state: osascript -e 'tell application "Tunnelblick" to get state of first configuration where name = "…"'.
2. Data retrieval: ssh -o BatchMode=yes $SSH_HOST "scontrol show node -o; squeue -h -o '%P|%T|%u'"; the two commands share a single SSH round trip.
3. GPU details (optional, GPU_DETAIL=1): the login node runs nvidia-smi --query-gpu=index,name,memory.used,memory.total,utilization.gpu on each GPU node in parallel, with the per-node timeout bounded by GPU_DETAIL_TIMEOUT. On clusters with pam_slurm_adopt enabled, only nodes on which the user has running jobs accept connections; the remaining nodes fall back to the statistics reported by Slurm.
4. Own jobs: squeue -u $USER -t R provides the job ID, name, elapsed time, time limit, nodes and GPUs per node.
5. Local aggregation: performed by awk, according to the rules below.

Aggregation rules:

• CPU usage is taken from CPUAlloc/CPUTot;
• The total GPU count is parsed from the Gres field, supporting formats such as gpu:a100:8(S:0-1), gpu:4 and gpu:2g.20gb:12,gpu:1g.20gb:4; the allocated count is taken from gres/gpu=N in AllocTRES (the field is omitted when the count is zero);
• The Partitions field is split on commas; a node belonging to multiple partitions is counted separately in each partition but only once in the global GPU total;
• Nodes in the DOWN, DRAIN, FAIL, MAINT or NOT_RESPONDING states are excluded from the available capacity;
• Host memory usage is computed as RealMemory − FreeMem, because AllocMem is always 0 on clusters that do not schedule memory.

4.1 Maximum Idle GPUs per Node

The gpu_max_free_node field in the output is the maximum number of idle GPUs (or MIG instances) on a single node; this value gives the upper bound on the size of a single-node job that can start immediately. In Figure 1, the gpu partition has 10/16 idle, but at most 8 idle GPUs on a single node; the gpu-v100 partition has 0/4 idle and at most 0 idle GPUs on a single node. The global idle count and the per-node idle count must be interpreted together: the former reflects the total, whereas the latter determines whether a multi-GPU job can obtain the required node at once.

4.2 GPU Usage of Jobs

With JOB_GPU_USAGE=1, srun --jobid=<id> --overlap -N1 -n1 nvidia-smi … is executed for each running job (up to 8) within its existing resource allocation. On clusters with ConstrainDevices=yes, this command sees only the GPUs held by the job, so no additional index mapping is required and no new resources are requested. This path is not restricted by pam_slurm_adopt, but each query is recorded in sacct as a job step (<jobid>.0, <jobid>.1, etc.); it is therefore disabled by default, and its query frequency is limited by JOB_GPU_INTERVAL (default 30 s), which keeps the number of job steps generated by the widget bounded.

The lower part of Figure 1 shows the display of this feature: job 123456 (train_llm, 2 GPUs) has been running for 1:23:45 with a time limit of 2 days; GPU0 uses 59.8/80 GB of memory at 97% utilisation, and GPU1 uses 39.3/80 GB at 88% utilisation. The memory bars are coloured by proportion (green below 60%, yellow for 60%–90%, red at 90% and above), and the elapsed time is incremented locally every second between two cluster queries.

5 Refresh Mechanism and Performance

Three measures are taken with respect to performance:

• Connection reuse: SSH enables ControlMaster=auto and ControlPersist=300; reusing the connection eliminates the handshake overhead, which the source comments quantify as a reduction from approximately 1 s to approximately 0.3 s; a complete refresh takes approximately 0.7–1.3 s.
• Query merging: node and queue information are retrieved together within the same session.
• Overlap suppression: the collection script uses a directory lock (mkdir) to prevent concurrent runs; if the previous collection has not yet finished (for example, because of a slow VPN or SSH response), the previous result is returned directly. A lock that has persisted for more than 90 s is regarded as the result of an abnormal process exit and is removed.

6 Installation and Configuration

6.1 Prerequisites

1. Password-less SSH: the widget runs in the background and cannot respond to interactive prompts, so key-based authentication is mandatory. If the key has a passphrase, UseKeychain yes and AddKeysToAgent yes must be added to ~/.ssh/config; a jump host can be declared via ProxyJump.
2. Non-interactive VPN: the Tunnelblick credentials must be stored in the macOS Keychain. VPNs that require a one-time password cannot be connected automatically; in that case AUTO_CONNECT=0 should be set.
3. Automation permission: on the first run, macOS asks whether Übersicht or SwiftBar may control Tunnelblick; this permission must be granted for automatic reconnection.

6.2 Installation Steps

Install either front end and launch it once (to create its plugin directory), then run:

git clone https://github.com/Yu-Xiang-Yang/slurm-gpu-widget.gitcd slurm-gpu-widgetbash install.shopen -e ~/.config/cluster-widget/config

After editing the configuration, verify the collection script; JSON output indicates that the configuration is valid:

~/.config/cluster-widget/cluster-status.sh~/.config/cluster-widget/cluster-status.sh --swiftbar

Running install.sh again updates the scripts and widgets but does not overwrite an existing configuration file.

6.3 Configuration Options

The configuration file is located at ~/.config/cluster-widget/config (template config.example); environment variables given on the command line take precedence over the file settings. The commonly used options are as follows:

To view all partitions and node details temporarily, the configuration can be overridden on the command line without affecting the configuration file:

GPU_ONLY=0 SHOW_NODES=1 PARTITIONS=gpu,compute ~/.config/cluster-widget/cluster-status.sh --swiftbar

For large partitions (approximately 100 nodes), SHOW_NODES=1 should be combined with PARTITIONS to limit the card height.

7 Output Format

The JSON object output in the default mode has the following structure (excerpt):

{  "lang": "en", "cluster": "Demo", "time": "13:58:32",  "vpn": "CONNECTED", "error": "",  "gpu_used": 10, "gpu_total": 20,  "partitions": [{    "name": "gpu", "nodes": 3, "idle_nodes": 1, "down_nodes": 1,    "cpu_used": 48, "cpu_total": 128, "gpu_used": 6, "gpu_total": 16,    "gpu_max_free_node": 8, "running": 2, "pending": 1, "mine": 0, "mig": false,    "model": "NVIDIA A100-SXM4-80GB", "mem_used": 1236992, "mem_total": 3072000  }]}

The field conventions are as follows:

• Memory values are in MiB;
• node_list appears only with SHOW_NODES=1;
• The gpus array of each node is non-empty only with GPU_DETAIL=1 and when the node accepts the query;
• With SHOW_MY_JOBS=1, a my_jobs array is appended to the top-level object, with each job containing elapsed_s and limit_s (UNLIMITED is recorded as −1); the top-level epoch records the collection time for local timekeeping.

8 Testing Without a Cluster

The repository’s mock/ directory provides synthetic scontrol and squeue output, allowing collection and front-end rendering to be verified in an environment without a cluster:

MOCK_DIR=mock bash cluster-status.shMOCK_DIR=mock SHOW_NODES=1 CLUSTER_NAME=Demo bash cluster-status.sh --swiftbar

Figure 1 was rendered from simulated data: the collection script was run with MOCK_DIR=mock, USER=testuser, SHOW_MY_JOBS=1, JOB_GPU_USAGE=1 and PARTITIONS=gpu,gpu-v100, and the resulting JSON was rendered by the Übersicht front-end source in the repository. The job names, memory figures and times in the figure are therefore synthetic values from the mock/ directory and do not correspond to a real cluster.

9 Design Trade-offs

10 Frequently Asked Questions

11 Extension to Other Schedulers

Only the remote commands and the awk parsing in the collection script are specific to Slurm. The PBS counterparts are pbsnodes -a and qstat, and the LSF counterparts are bhosts and bqueues. Once these two parts are replaced, neither the JSON structure nor the two front ends require any change.

12 Project Repository

GitHub: https://github.com/Yu-Xiang-Yang/slurm-gpu-widget (MIT License, with Chinese and English READMEs).

Paper Information

1. Background and Research Questions

As transportation networks continue to grow in length and scale, an increasing number of extra-long and large transportation infrastructures are located near, span or cross active faults. Fault movement produces permanent ground deformation: in the 1999 Chi-Chi earthquake, the fault rupture passed through the Pi-feng Bridge and caused the collapse of three spans on its southern side. High-speed transportation projects commonly adopt foundations with embedment, such as pile foundations and caissons, yet the response of such foundations to fault movement remains unclear.

Previous centrifuge tests have investigated the influence of embedment depth (Ashtiani et al.) or foundation position (Loli et al.) on rupture propagation and foundation displacement. The paper identifies two shortcomings in this body of work:

1. Structural load is generally neglected. In practice the structural load is considerable, and neglecting it may bias the assessment.
2. Existing classifications rely on a known relative position between rupture and foundation. In engineering practice, the propagation path of the rupture through the overburden is difficult to predict accurately in advance, so methods that depend on this prior information have limited applicability in fault-resistant design.

To address these issues, the study conducts systematic tests with foundation position, embedment depth and load as variables, and uses displacement characteristics observable at the ground surface as the criterion for identifying interaction modes.

2. Test Method

2.1 Test Apparatus and Similitude Relations

Given the large number of test cases and the objective of identifying interaction modes rather than obtaining precise displacements, the study adopts 1g model tests (previous comparative studies have shown that the main rupture patterns in 1g and centrifuge tests are similar). The fault simulation apparatus was developed in-house (Figure 1); the model box measures 1600 mm × 300 mm × 800 mm (length × width × height) and can simulate normal and reverse fault movement at different dip angles.

Figure 1　Front view of the fault simulation apparatus: ① screw jack; ② linear bearing; ③ side plate; ④ hanging wall; ⑤ footwall; ⑥ sand box (Fig. 2 in the original paper)

The main test parameters are as follows:

• Fault conditions: reverse fault with dip angle $\alpha = 60^\circ$ and a displacement rate of 0.5 mm/s; loading stops when the vertical offset reaches 120 mm.
• Model soil: Fujian standard sand with a relative density $D_r$ of 60% and a target dry unit weight of 15.7 kN/m³; peak friction angle 35.9°, residual friction angle 30.7°, dilation angle 7.39°.
• Similitude relations: sand is used to model a gravelly soil prototype, with a geometric similitude ratio $C_L = 1:23$, a unit weight similitude ratio $C_\gamma = 1:1.3$, an elastic modulus and stress similitude ratio $C_E = C_\sigma = 1:30$, and a strain similitude ratio $C_\varepsilon = 1:1$.
• Foundation model: an aluminium box simulates a rigid embedded foundation, with width $B = 100$ mm and a mass of about 5.05 kg; the load is applied by sand and weights placed inside the box.
• Instrumentation: a 6000 × 4000 pixel camera captures images at 1 s intervals, and particle image velocimetry (PIV) is used to analyse soil deformation; an LVDT measures the vertical displacement of the hanging wall with an accuracy of 0.01 mm.

2.2 Model and Test Programme

The model is illustrated in Figure 2: the overburden thickness is $H = 600$ mm; $D$ is the foundation embedment depth; $q$ is the foundation load; $\Delta h$ is the vertical bedrock offset; M is the free-field rupture outcrop point; $S$ is the horizontal distance from the hanging-wall-side edge of the foundation to point M, and $S/B$ characterises the foundation position.

Figure 2　Schematic of the model boundary conditions (Fig. 4 in the original paper)

Cases are named according to the rule Case-depth (cm)-position (S/B)-load (kPa). Model loads of 2.55–11.05 kPa correspond, via the stress similitude ratio, to prototype loads of 77–330 kPa; embedment depths of 10, 20 and 40 cm correspond to foundation width-to-depth ratios of 1/1, 1/2 and 1/4, determined with reference to the Specifications for Design of Foundation of Highway Bridges and Culverts (JTG 3363—2019). All cases are listed below (Table 4 in the original paper):

2.3 Data Processing

The rupture zone is characterised by the PIV strain field: a pair of images is analysed for every 1 mm of offset, and the region where the strain reaches −0.1 is defined as the rupture zone. Vertical ground surface displacement is taken at 29 measurement points within the range from 750 mm to the left to 550 mm to the right of the fault point, fitted by cubic B-spline interpolation, and the displacement gradient is obtained from the fitted function. In the presence of a foundation, the surface displacement no longer follows the S-shaped distribution commonly observed in the free field; B-splines are therefore used for fitting instead of an S-shaped function.

3. Free-Field Test

Under free-field conditions (Figure 3), the rupture propagates approximately along a straight line in the early stage of bedrock offset, then gradually bends toward the footwall as the offset increases and finally outcrops at the ground surface. The horizontal distance from the outcrop point to the bedrock offset point is 465 mm, i.e. 77% of the overburden thickness, close to the centrifuge results of Bransby et al. (80%) and Ashtiani et al. (82%). The rupture zone identified by PIV is consistent with visual observation, and all subsequent analyses represent the rupture zone by PIV strain contours.

Figure 3　Free-field rupture propagation: (a) test observation; (b) PIV strain rate contour (Fig. 5 in the original paper)

4. Influence of Individual Factors

4.1 Foundation Position

Figure 4 shows rupture propagation at different positions for an embedment depth of 20 cm without additional load (the white line indicates the free-field rupture path):

• $S/B = 3$: the foundation is far from the free-field outcrop point, the rupture acts directly on the foundation base, the foundation is uplifted, and a passive rupture zone forms on the footwall side;
• $S/B = 2$: the rupture is intercepted by the foundation, an additional rupture zone forms on the hanging-wall side, and a passive rupture zone still forms on the footwall side;
• $S/B = 1$: the foundation is close to the outcrop point, the rupture is completely blocked by the foundation on the hanging-wall side and outcrops along the foundation edge.

The closer the foundation is to the free-field rupture path, the more the rupture distribution shifts from the footwall side to the hanging-wall side, consistent with the centrifuge observations of Loli et al.; the farther the foundation lies toward the hanging wall, the larger the foundation displacement and rotation.

Figure 4　Rupture propagation for different foundation positions: (a) Case 20-3-0; (b) Case 20-2-0; (c) Case 20-1-0 (Fig. 6 in the original paper)

4.2 Foundation Embedment Depth

The influence of embedment depth depends on whether it changes the contact position between the rupture and the foundation. For $S/B = 1$, increasing the embedment depth has little effect on rupture propagation, and foundation displacement and rotation decrease with increasing depth. For $S/B = 3$, increasing the embedment depth has an effect similar to reducing $S/B$: the rupture shifts from the footwall side to the hanging-wall side and the vertical displacement of the foundation decreases continuously, but the rotation and horizontal displacement increase when the depth increases from 10 cm to 20 cm. The effects of the factors are thus mutually coupled, and the change in response cannot be determined from a single factor alone.

4.3 Foundation Load

The influence of load is examined for contact and non-contact situations:

• Contact situation ($S/B = 2$, $D = 10$ cm): as the load increases, the rupture shifts from the footwall side of the foundation to bifurcating around both sides of the foundation, and finally to the hanging-wall side.
• Non-contact situation ($S/B = 3$, $D = 10$ cm, Figure 5): without load, the rupture passes beneath the foundation; at small loads (2.55 and 3.35 kPa), the rupture shifts toward the footwall side, away from the foundation, i.e. the load “repels” the rupture; as the load increases further (4.25–11.05 kPa), the rupture is “attracted” back to both sides of the foundation.

In both situations, the foundation rotation first increases and then decreases, with the maximum rotation occurring in the critical cases in which the rupture shifts from the footwall side to the hanging-wall side (Case 10-2-3.35 and Case 10-3-3.35). This result indicates that a foundation located outside the free-field rupture path is not necessarily safe: a large structural load can draw the rupture toward the foundation and produce significant rotation.

Figure 5　Rupture propagation under different loads in the non-contact situation (Case 10-3-0/2.55/3.35/4.25/7.65/11.05, Fig. 14 in the original paper)

5. Three Interaction Modes

5.1 Classification Indices and Results

To compare all cases, the study selects five indices, each normalised by its maximum value: horizontal displacement, vertical displacement and rotation of the foundation, together with the difference $\Delta Y$ between the peak surface displacements on the hanging wall and footwall and the horizontal distance $\Delta X$ between the two peak points. Larger $\Delta X$ and $\Delta Y$ indicate surface uplift concentrated on one side; smaller values indicate a distribution closer to the uniform free-field pattern. On this basis, the 25 cases with foundations are divided into three modes: Bottom Contact, Sidewall-Bottom Contact and Sidewall Contact (Figure 6):

Figure 6　Classification of three embedded foundation–fault interaction modes: (a) normalised indices of all cases; (b) ranking and grouping; (c) schematic of the modes (Fig. 18 in the original paper)

When the load is negligible, the three modes correspond one-to-one with the classification of Loli et al. based on subsurface rupture patterns. The classification method offers two improvements: it accounts for structural load, which is closer to engineering practice; and it uses surface and foundation displacement as criteria, which are easier to monitor than subsurface rupture paths, so that the mode can be identified through monitoring when the rupture path cannot be predicted.

5.2 Multi-Factor Coupling in Mode Transition

Figure 7 places the three modes in a three-dimensional parameter space with foundation position, embedment depth and load as axes; transition interfaces exist between the modes. A change along a single axis can trigger a mode transition, for example:

• Changing only the embedment depth: Case 40-2-0 → Case 10-2-0;
• Changing only the load: Case 10-3-0 → Case 10-3-11.05;
• Changing only the position: Case 10-3-0 → Case 10-2-0.

When the three factors vary simultaneously (e.g. Case 10-3-0 → Case 20-3-4.25), a mode transition occurs when the resultant direction crosses an interface. Within the range of tests completed, the study confirms one direction: with increasing load, increasing embedment depth and decreasing $S/B$, the interaction mode evolves along “bottom contact → sidewall-bottom contact → sidewall contact”. Owing to the limited number of tests, the exact location of the interfaces cannot yet be determined, but the result demonstrates the feasibility of studying mode transitions through combined factors.

Figure 7　Coupled influence of foundation position, embedment depth and load on interaction mode transition (Fig. 20 in the original paper)

5.3 Evolution of Rupture Patterns during Transition

For an embedment depth of 40 cm without load, as the foundation position changes progressively from $S/B = 1$ to 5 (Test 17–24, Figure 8), the rupture pattern passes through the following stages:

1. The rupture contacts the upper part of the foundation sidewall: the main rupture zone (MR) deflects and then outcrops;
2. The contact point moves down to the middle of the sidewall: a secondary rupture zone (SR I) forms and outcrops;
3. The contact point moves further down: MR contacts both the sidewall and the base, the number of upper secondary rupture zones first increases and then decreases, and a concave-upward passive rupture zone (PR) begins to form on the footwall side of the foundation;
4. The rupture contacts the bottom corner of the foundation (Test 22): the upper secondary ruptures disappear, MR propagates upward along the foundation sidewall–soil interface, and PR changes to a concave-downward shape;
5. The foundation moves further away (Test 24): the passive rupture zone on the footwall side gradually becomes the main rupture zone.

When the rupture contacts the upper half of the sidewall, the overall displacement and rotation of the foundation are small; they increase significantly when the rupture contacts the bottom corner and the base. The abrupt increase in rotation for Case 40-3.5-0 can be attributed to two factors: its sidewall contact point is closer to the bottom than that of Case 40-3-0, which weakens the sidewall restraint; and its bottom contact area is smaller than that of Case 40-4-0, which limits translation. Together these lead to increased rotation.

Figure 8　Evolution of rupture patterns with foundation position (Case 40-1/2/3/3.5/4/5, Fig. 21 in the original paper)

6. Interaction Mechanisms

6.1 Mechanism 1: Foundation Stiffness Alters the Rupture Path

When the rupture directly contacts the foundation, the rigid foundation alters the displacement pattern of the surrounding soil. After the rupture on the hanging-wall side is blocked by the foundation, it seeks a new outcrop along the path of minimum energy dissipation: a small change in path manifests as trajectory deflection, and a large change manifests as the generation of new secondary rupture zones. The closer the contact point is to the ground surface, the lower the energy required for deflected outcropping; the deeper the contact point, the greater the tendency to form one or more secondary ruptures. When the foundation approaches the bedrock offset point, the rupture direction becomes nearly parallel to the sidewall and turns into a shear band developing along the foundation–soil interface.

The shape of the passive rupture zone on the footwall side is related to the direction of foundation displacement. The closer the foundation is to the bedrock offset point, the closer the ratio of its vertical to horizontal displacement approaches the bedrock offset direction $\tan\alpha = 1.732$; the foundation motion changes from predominantly horizontal (similar to the translation of a retaining wall) to following the bedrock offset, and the passive rupture zone correspondingly changes from a concave-upward logarithmic spiral to a concave-downward logarithmic spiral.

6.2 Mechanism 2: Additional Stress Causes Rupture Deflection

When the rupture passes beneath the foundation, the governing factors are the principal stress axis rotation and soil densification induced by the additional stress from the foundation. The study assumes that the free-field rupture already reflects the combined effects of the initial in-situ stress and the stress change caused by bedrock offset, that the three do not interact, and considers only the effect of the additional stress. The base pressure is approximated as a uniformly distributed load, and the additional stress coefficients $K_x$, $K_z$ and $K_{zx}$ are obtained from the Boussinesq solution:

$$ \sigma_x = K_x p + K_0 \gamma z, \qquad \sigma_z = K_z p + \gamma z, \qquad \tau_{zx} = K_{zx} p $$

The rotation angle of the principal stress axis and the stress ratio characterising the degree of densification are, respectively,

$$ \Delta\alpha = \frac{1}{2}\arctan\frac{2\tau_{zx}}{\sigma_x - \sigma_z}, \qquad K = \frac{\sigma_1 + \sigma_2}{K_0 \gamma z + \gamma z} $$

In the tests, the rupture beneath the foundation was observed to deflect toward the footwall side (Case 10-3-3.35) and toward the hanging-wall side (Case 10-3-11.05), with the deflection direction corresponding to the direction of principal stress axis rotation (Figure 9). The PIV results also reveal a densified zone beneath the foundation that resists deformation, i.e. an “elastic core”.

Figure 9　Rupture deflection and contours of the principal stress axis rotation angle: (a) Case 10-3-3.35, deflection toward the footwall side; (b) Case 10-3-11.05, deflection toward the hanging-wall side; (c) contours of Δα (Fig. 25 in the original paper)

Defining the additional-stress influence zone by $\lvert\Delta\alpha\rvert > 5^\circ$ and $K > 0.2$ provides a unified explanation of the coupled effects of the three factors (Figure 10):

• Load determines the size of the influence zone: when the load increases from 3.35 kPa to 11.05 kPa, both the principal stress rotation zone and the densified zone expand significantly, their overlap with the rupture path changes, and the deflection direction changes from the footwall side to the hanging-wall side;
• Position determines the location of the influence zone relative to the rupture path;
• Embedment depth affects both the location and the size of the influence zone: for the same $q = 4.25$ kPa and the same relative position between the foundation base and the rupture, the influence zone of the foundation embedded at 40 cm is significantly smaller than that of the foundation embedded at 10 cm, and its effect on rupture propagation is small.

The greater the overlap between the free-field rupture path and the additional-stress influence zone, the more pronounced the rupture deflection caused by load changes.

Figure 10　Schematic of the coupled mechanism of foundation load with position and embedment depth (Fig. 27 in the original paper)

7. Comparison with Field Cases and Design Recommendations

The study compares two typical failure forms with earthquake damage cases. When the action is applied mainly to the foundation base, the foundation moves together with the soil mass and undergoes large horizontal or vertical displacement (e.g. in the 1999 Kocaeli earthquake, the Arifiye overpass shifted laterally as a whole and four spans collapsed in succession). When the action is applied mainly to the sidewall, the soil exerts significant shear on the foundation (e.g. in the 1999 Chi-Chi earthquake, the Wu-Shi Bridge experienced about 2 m of reverse fault offset, and piers P1W and P2W were nearly sheared off). In field cases, the bottom contact mode generally corresponds to severe damage; the sidewall contact mode corresponds to minor damage in some cases, although cases of severe shear failure also exist; the sidewall-bottom contact mode, as a transitional mode, is difficult to identify in field cases.

Based on these results, the paper proposes the following design recommendations:

1. Optimise foundation type and embedment depth: preferably adopt shallow embedment to avoid contact with the rupture; when contact is unavoidable, increase the embedment depth so that the interaction is confined to the upper part of the sidewall rather than the lower part of the sidewall or the base.
2. Control structural load: reduce the structural self-weight when the rupture is expected to pass beneath the foundation; when contact is unavoidable, increase the self-weight appropriately to promote a transition to the safer sidewall contact mode.
3. Adopt mode-specific measures: for bottom contact, an underlying soft layer can be installed to absorb the offset displacement; for sidewall contact, a fault-resistant wall layer can be installed; for bottom-corner contact, uplift piles can be used to reduce foundation rotation.
4. Establish monitoring and emergency response systems: install displacement meters or inclinometers at critical locations, and, once an adverse interaction is identified, promptly implement measures such as traffic control, structural strengthening or evacuation.

8. Limitations

1. Scale effects: in 1g tests the soil stiffness is lower than in the field, which may overestimate the shear resistance of the structure, particularly in the sidewall contact mode; the higher stress level in the field may lead to more concentrated shear bands. Previous comparative studies have also shown that 1g and centrifuge tests differ in rupture zone thickness, propagation rate and the formation of secondary ruptures.
2. Rigid foundation assumption: the stiffness of the aluminium foundation is much greater than that of the surrounding soil, so the conclusions mainly represent high-stiffness, shallowly embedded foundations. When the foundation stiffness approaches that of the soil, deformation becomes more pronounced, and the sidewall contact and sidewall-bottom contact modes may also lead to shear failure; at lower stiffness, the rupture may shear through the foundation and continue propagating.
3. Future work: centrifuge tests at elevated gravity are planned to compare rupture patterns under different failure mechanisms (in particular the formation of secondary rupture zones) and to examine whether structural damage under centrifuge conditions differs significantly from the 1g test results.

9. Main Conclusions

1. An interaction classification framework is proposed based on ground surface displacement, foundation displacement and rupture propagation characteristics: when the rupture path is predictable, targeted fault-resistant design can be carried out accordingly; when it is not, the mode can be identified and addressed early through displacement monitoring.
2. Transitions among the bottom contact, sidewall-bottom contact and sidewall contact modes are jointly determined by foundation position, embedment depth and structural load; different parameter combinations can produce similar evolution trends, and transition interfaces exist between the modes.
3. Foundation load influences the rupture indirectly by altering the stress state of the soil: a moderate load can temporarily “push” the rupture away from the foundation, whereas an excessive load “attracts” the rupture to both sides of the foundation and increases the risk of rotation; the effect of load diminishes rapidly with increasing embedment depth.
4. Foundation embedment depth and structural load should be optimised in conjunction with rupture path prediction, supplemented by displacement monitoring at critical locations and emergency response measures.

Citation

Guan L, Ling D, Hu C, Yu X, Song K. Experimental study on the interaction mechanisms of soil overlying embedded foundations under reverse faults. Transportation Geotechnics, 2025, 54: 101596. https://doi.org/10.1016/j.trgeo.2025.101596

@article{guan2025experimental,  title   = {Experimental study on the interaction mechanisms of soil overlying embedded foundations under reverse faults},  author  = {Guan, Li and Ling, Daosheng and Hu, Chengbao and Yu, Xiangyang and Song, Kunming},  journal = {Transportation Geotechnics},  volume  = {54},  pages   = {101596},  year    = {2025},  doi     = {10.1016/j.trgeo.2025.101596}}

Note: the figures and tables in this post are reproduced from the original paper (published by Elsevier); the captions are paraphrased and are provided for academic exchange only. Fig. 1, Fig. 23 and Fig. 26(a) of the original paper are adapted from third-party literature and are not reproduced here.

Paper Information

1. Background

Buffer clay layers are widely used as barrier layers in landfills, industrially contaminated sites and radioactive waste repositories. Three classes of mutually coupled processes take place simultaneously in a buffer layer:

1. Chemical process: concentration gradients drive contaminant diffusion, which determines the breakthrough time of contaminants through the buffer layer;
2. Hydro-mechanical process: external loading compresses the soil skeleton, generating excess pore water pressure and driving pore fluid seepage, which in turn carries contaminants by advection;
3. Chemo-mechanical feedback: changes in pore fluid concentration cause volume change of the soil (chemo-osmotic consolidation), and the concentration gradient itself also drives pore water flow (chemo-osmotic effect).

Existing studies have two limitations. First, many contaminant transport models treat the soil as an incompressible medium and neglect the two-way coupling between consolidation and transport. Second, existing analytical solutions for CHM coupled consolidation (e.g. Zheng et al. 2021, 2023) assume a constant mechanical load. In actual landfills, waste is placed in stages, so the load acting on the buffer layer increases gradually with time; studies on one-dimensional consolidation theory have also shown that the loading process is a key factor governing the development of consolidation. The paper therefore establishes an analytical solution for CHM coupled consolidation under time-dependent loading.

2. Mathematical Model

2.1 Problem Description and Basic Assumptions

As shown in Figure 1, the top surface of the buffer clay layer is subjected to a mechanical load $q(t)$ and is in contact with a chemical solution of concentration $c_0$; the bottom surface is either impermeable (Case A, single-sided drainage) or permeable (Case B, double-sided drainage). The basic assumptions are: the soil layer is fully saturated, and the coefficient of volume compressibility and the hydraulic conductivity remain constant during consolidation; soil particles and pore water are incompressible; deformation is small, and seepage and solute transport occur only in the vertical direction.

Figure 1　Schematic of one-dimensional CHM coupled consolidation of a buffer clay layer: (a) Case A, single-sided drainage; (b) Case B, double-sided drainage (Fig. 1 in the original paper)

Two typical forms of time-dependent loading are considered (Figure 2):

• Ramp loading: $q(t) = q_0 t / t_0$ for $t \le t_0$, and $q(t) = q_0$ for $t > t_0$;
• Exponential loading: $q(t) = q_0 \left[1 - \exp(-bt)\right]$.

Figure 2　Two types of time-dependent loading: (a) ramp loading; (b) exponential loading (Fig. 2 in the original paper)

2.2 Constitutive Relations and Conservation Equations

The change in porosity is the superposition of two parts, one due to the effective stress increment and the other due to the concentration change, where $m_v$ is the coefficient of volume compressibility under mechanical loading and $m_c$ is the coefficient of volume change due to concentration change:

$$ \Delta n = -m_v \left[q(t) - u\right] - m_c (c - c_0) $$

The pore water velocity is controlled by both the pore pressure gradient and the concentration gradient (chemo-osmotic effect), and the solute flux comprises a diffusion term and an ultrafiltration term:

$$ v = -\frac{k}{\gamma_w}\frac{\partial u}{\partial z} + k_c \frac{\partial c}{\partial z}, \qquad J = -D \frac{\partial c}{\partial z} + D_u \frac{\partial u}{\partial z} $$

where $k$ is the hydraulic conductivity, $k_c$ is the chemo-osmotic conductivity, $D$ is the effective diffusion coefficient and $D_u$ is the ultrafiltration coefficient. In addition, the amount of adsorbed water varies with concentration, which changes the pore fluid density; the parameter $\xi$ denotes the relative change in total pore fluid density per unit concentration increment. Substituting the above relations into the mass conservation equations of the fluid phase and the solute yields, after rearrangement, the coupled equations in terms of the excess pore water pressure $u$ and the concentration $c$:

$$ \frac{\partial u}{\partial t} = W_w \frac{\partial^2 u}{\partial z^2} + W_c \frac{\partial^2 c}{\partial z^2} + \frac{\mathrm{d} q}{\mathrm{d} t} $$

$$ \frac{\partial c}{\partial t} = C_w \frac{\partial^2 u}{\partial z^2} + C_c \frac{\partial^2 c}{\partial z^2} $$

The coefficients $W_w$, $W_c$, $C_w$ and $C_c$ are combinations of material parameters such as $k$, $k_c$, $m_v$, $m_c$, $D$, $D_u$, $\xi$, $n_0$ and $c_0$. $W_c$ and $C_w$ are cross-coupling terms: $W_c$ reflects the effect of the concentration field on pore pressure, and $C_w$ reflects the effect of the pore pressure field on concentration.

2.3 Boundary Conditions

Top surface: $u(L,t) = 0$, $c(L,t) = c_0$. Bottom surface: zero-gradient conditions for Case A ($\partial u/\partial z = 0$, $\partial c/\partial z = 0$); zero-value conditions for Case B ($u = 0$, $c = 0$).

3. Decoupling Method and Analytical Solution

The diffusion terms of the above system are coupled in matrix form. The paper introduces the linear combination $\varphi = p_1 u + p_2 c$ and requires the combination coefficients to satisfy

$$ (W_w - Q) p_1 + C_w p_2 = 0, \qquad W_c p_1 + (C_c - Q) p_2 = 0 $$

that is, $(p_1, p_2)$ is a left eigenvector of the diffusion coefficient matrix $\mathbf{A}$ (first row $W_w$, $W_c$; second row $C_w$, $C_c$), and $Q$ is the corresponding eigenvalue. The condition for a non-trivial solution gives two eigenvalues:

$$ Q_{1,2} = \frac{1}{2}\left[ C_c + W_w \pm \sqrt{(C_c - W_w)^2 + 4 C_w W_c} \right] $$

This yields two mutually independent inhomogeneous diffusion equations ($i = 1, 2$):

$$ \frac{\partial \varphi_i}{\partial t} - Q_i \frac{\partial^2 \varphi_i}{\partial z^2} = \beta_i \frac{\mathrm{d} q}{\mathrm{d} t} $$

where $\varphi_1 = u + p_{21} c$, $\varphi_2 = p_{12} u + c$, $\beta_1 = 1$ and $\beta_2 = p_{12}$. The decoupled equations are solved by separation of variables together with the Laplace transform and its inverse, giving series solutions for ramp loading and exponential loading under Case A and Case B. The eigenvalues are $\lambda_N = (N + 1/2)\pi / L$ ($N = 0, 1, 2, \ldots$) for Case A and $\lambda_N = N\pi / L$ ($N = 1, 2, \ldots$) for Case B. Finally, back-substitution through

$$ u = \frac{p_{21}\varphi_2 - \varphi_1}{p_{12}p_{21} - 1}, \qquad c = \frac{p_{12}\varphi_1 - \varphi_2}{p_{12}p_{21} - 1} $$

gives the analytical expressions for pore pressure and concentration. The essential point of the method is that, provided the two eigenvalues of $\mathbf{A}$ are distinct positive real numbers, the cross-coupled system can be transformed by eigendecomposition into two standard diffusion problems, so that the solution techniques of classical consolidation theory remain applicable.

4. Verification of the Analytical Solution

The original coupled system is solved directly with the mathematics interface of COMSOL Multiphysics and compared with the analytical solution. In the example, the soil layer thickness is 1 m, the series is truncated at $N = 100$ terms, and the baseline parameters are listed in the table below (Table 1 in the original paper).

Figures 3 and 4 show the pore pressure distributions at different times under single-sided and double-sided drainage, respectively; the analytical solutions agree with the finite element results.

Figure 3　Pore pressure distributions at different times for Case A: (a) ramp loading; (b) exponential loading (Fig. 3 in the original paper)

Figure 4　Pore pressure distributions at different times for Case B: (a) ramp loading; (b) exponential loading (Fig. 4 in the original paper)

Figures 3 and 4 reveal the following trends:

• The time scales of the two processes differ by a factor of about 20: the pore pressure induced by mechanical loading dissipates within about 10 years, whereas solute diffusion requires about 200 years to reach a steady state.
• Origin of negative pore pressure: in Case A, a distinct negative excess pore water pressure appears at $t = 10$ years, and the pore pressure essentially vanishes after $t > 100$ years. The early-stage pore pressure is dominated by mechanical loading; after the load-induced pore pressure has dissipated, the concentration gradient drives pore water from regions of low concentration toward regions of high concentration, which, under the solution boundary condition at the top surface, manifests as outward seepage and thus produces negative pore pressure.
• Effect of boundary conditions: at $t = 10$ years, the excess pore water pressure in Case B has fully dissipated, whereas a considerable negative pore pressure remains in Case A. The pore pressure distribution in Case B is no longer symmetric about the mid-plane of the layer as in the Terzaghi solution; because the solute diffuses from the top downward, the negative pore pressure in the upper part of the layer exceeds that in the lower part.

Figure 5　Concentration distributions at different times for Case A: (a) ramp loading; (b) exponential loading (Fig. 5 in the original paper)

Figure 6　Concentration distributions at different times for Case B: (a) ramp loading; (b) exponential loading (Fig. 6 in the original paper)

Figures 5 and 6 show that solute transport is faster under double-sided drainage than under single-sided drainage. At $t = 200$ years, the concentration in Case A tends to be uniform with depth (close to $c_0$), whereas Case B exhibits a linear distribution from 0 at the bottom to $c_0$ at the top, consistent with the steady-state solutions under the two bottom boundary conditions.

5. Parametric Sensitivity Analysis

Taking ramp loading with single-sided drainage (Case A) as the reference case and $t = 1$ year as the observation time, the parameters are varied one at a time to examine their influence. Representative results are shown in Figures 7–10.

Figure 7　Effect of the effective diffusion coefficient D: (a) concentration distribution; (b) pore pressure distribution (Fig. 7 in the original paper)

When $D$ increases from $1\times10^{-11}$ to $1\times10^{-10}$ and $1\times10^{-9}$ m²/s, the solute diffusion depth at $t = 1$ year is approximately 0.1, 0.35 and 1 m, respectively. A larger $D$ results in slower pore pressure dissipation: the pore pressure at the bottom is about 25 kPa for $D = 1\times10^{-11}$ m²/s and increases to about 38 kPa for $D = 4\times10^{-9}$ m²/s. When $D$ is small, the concentration gradient is large, and chemo-osmotic consolidation produces negative pore pressure near the top of the layer.

Figure 8　Effect of the hydraulic conductivity k: (a) concentration distribution; (b) pore pressure distribution (Fig. 9 in the original paper)

$k$ has almost no influence on solute transport but a significant influence on pore pressure dissipation. For $k = 1\times10^{-10}$ m/s, the pore pressure at the bottom is about 25 kPa; for $k > 4\times10^{-10}$ m/s, the pore pressure due to mechanical loading has essentially dissipated within 1 year, and the negative pore pressure induced by the concentration gradient becomes observable. The reason $k$ does not affect solute transport is that, under small deformation, the advective distance caused by consolidation is limited and advection ceases once consolidation is complete, so its contribution to solute transport is much smaller than that of diffusion. Advection becomes the dominant factor only when a constant hydraulic head difference exists between the top and bottom surfaces of the layer, a situation outside the scope of the study.

Figure 9　Effect of the pore fluid density change coefficient ξ: (a) concentration distribution; (b) pore pressure distribution (Fig. 11 in the original paper)

$\xi$ significantly affects both transport and pore pressure: a larger $\xi$ results in faster solute transport and a larger negative pore pressure due to concentration change. For $\xi = 4\times10^{-3}$ m³/kg, the negative pore pressure at the bottom falls below −150 kPa, a magnitude exceeding the final load value $q_0$ (100 kPa).

Figure 10　Effect of the loading duration t₀ of the ramp load: (a) concentration distribution; (b) pore pressure distribution (Fig. 14 in the original paper)

The influence of $t_0$ on solute transport is negligible, because the time required for mechanical consolidation is much shorter than the solute transport time. A larger $t_0$ corresponds to a lower loading rate and a smaller pore pressure induced by mechanical loading. For $t_0 = 100$ years, the positive pore pressure due to loading and concentration change is essentially negligible, the pore pressure becomes negative, and chemo-osmotic consolidation dominates.

The effects of all eight parameters are summarised as follows:

6. Main Conclusions

1. All parameters studied affect the generation and dissipation of pore pressure, but only $D$, $D_u$ and $\xi$ significantly affect contaminant transport; the influence of the remaining parameters is negligible.
2. Hydraulic and diffusive boundary conditions significantly affect pore pressure distribution and contaminant transport: under double-sided drainage (Case B), both pore pressure dissipation and contaminant transport are faster than under single-sided drainage (Case A).
3. Increases in mechanical load and in concentration produce positive pore pressure, whereas the concentration gradient produces negative pore pressure. Early-stage pore pressure is dominated by mechanical loading, and late-stage pore pressure is dominated by the negative pore pressure induced by the concentration gradient; the two differ in magnitude.
4. The longer the duration of mechanical loading (i.e. the lower the loading rate), the more pronounced the negative pore pressure induced by the concentration gradient.

7. Engineering Implications

The above conclusions have two direct implications for the design of buffer clay layers. First, the contaminant breakthrough time is controlled mainly by $D$, $D_u$, $\xi$ and the bottom boundary condition, whereas permeability and compressibility parameters have a negligible effect on it. Second, the slower the filling process, the more prominent the negative pore pressure induced by chemical osmosis; evaluating the pore pressure and effective stress state of the buffer layer under a constant-load assumption will therefore introduce deviations. In addition, the analytical solution corresponds to a linear coupled diffusion system and can serve as a benchmark for numerical methods (including physics-informed neural networks, PINNs) applied to multiphysics coupling problems, which connects with the research direction of the post on this site PINN solution of Biot consolidation in saturated soil (in Chinese).

Citation

Li X, Shen Y, Yu X, Zhang Z, Zhang W. Analytical solution for one-dimensional chemo-hydro-mechanical coupled consolidation under time-dependent loading in buffer clay layer. Canadian Geotechnical Journal, 2025, 62: 1–13. https://doi.org/10.1139/cgj-2024-0145

@article{li2025analytical,  title   = {Analytical solution for one-dimensional chemo-hydro-mechanical coupled consolidation under time-dependent loading in buffer clay layer},  author  = {Li, Xibin and Shen, Yanghai and Yu, Xiangyang and Zhang, Zhiqing and Zhang, Wenjie},  journal = {Canadian Geotechnical Journal},  volume  = {62},  pages   = {1--13},  year    = {2025},  doi     = {10.1139/cgj-2024-0145}}

Note: the figures and tables in this post are reproduced from the original paper (© 2025 The Author(s), published by Canadian Science Publishing); the captions are paraphrased and are provided for academic exchange only.

1. Problem Statement: Invertibility versus Readability

Two propositions at different levels must be distinguished (all of the following concern the ordinary Fourier transform; the windowed case is treated in Section 4.3):

The first three rows belong to the domain of invertibility and the last two to the domain of readability; the two do not conflict. A common reasoning error is to conjoin rows 2 and 3 and erroneously infer row 4. $f(t)$ and $\hat f(\omega)$ are two mutually exclusive representations of the same information and cannot both be presented at high resolution on the same chart.

2. The Heisenberg–Weyl Inequality

2.1 Statement of the Theorem

Let $f \in L^2(\mathbb{R})$, $\lVert f \rVert_2 = 1$, with Fourier transform $\hat f(\omega)$. Define the centres and spreads in time and frequency:

$$ t_0 = \int t \lvert f(t)\rvert^2 dt, \qquad \Delta t^2 = \int (t-t_0)^2 \lvert f(t)\rvert^2 dt $$

$$ \omega_0 = \frac{1}{2\pi}\int \omega \lvert \hat f(\omega)\rvert^2 d\omega, \qquad \Delta\omega^2 = \frac{1}{2\pi}\int (\omega-\omega_0)^2 \lvert \hat f(\omega)\rvert^2 d\omega $$

Then it always holds that

$$ \Delta t \cdot \Delta \omega \geq \frac{1}{2} \qquad\Longleftrightarrow\qquad \Delta t \cdot \Delta f \geq \frac{1}{4\pi} \approx 0.0796 $$

In signal analysis this relation is called the Gabor limit. It is the same mathematical theorem as the position–momentum uncertainty relation in quantum mechanics, with only the pair of conjugate variables replaced.

2.2 Proof

Without loss of generality take $t_0 = \omega_0 = 0$. By Parseval’s theorem and $\mathcal{F}[f^{\prime}] (\omega) = i\omega\hat f(\omega)$, one has $\Delta\omega^2 = \lVert f^{\prime} \rVert^2$. Hence

$$ \Delta t^2 \Delta\omega^2 = \lVert tf \rVert^2 \lVert f^{\prime} \rVert^2 \geq \lvert \langle tf, f^{\prime} \rangle \rvert^2 \geq \lvert \operatorname{Re}\langle tf, f^{\prime} \rangle \rvert^2 $$

The first inequality is the Cauchy–Schwarz inequality. Noting that $2\operatorname{Re}\big(\overline{f}f^{\prime}\big) = (\lvert f\rvert^2)^{\prime}$, integration by parts of the real-part term gives:

$$ \operatorname{Re}\langle tf, f^{\prime} \rangle = \frac{1}{2}\int t \big(\lvert f\rvert^2\big)^{\prime} dt = -\frac{1}{2}\int \lvert f\rvert^2 dt = -\frac{1}{2} $$

Substituting back yields $\Delta t^2 \Delta\omega^2 \geq 1/4$, which completes the proof.

2.3 Condition for Equality

Equality in Cauchy–Schwarz requires $f^{\prime} = -\lambda t f$ ($\lambda > 0$), whose solution is

$$ f(t) = C e^{-\lambda t^2/2} $$

That is, the lower bound is attained if and only if $f$ is a Gaussian (or a modulated and translated Gaussian). Taking $f(t) = (\pi\sigma^2)^{-1/4}e^{-t^2/2\sigma^2}$, one has $\hat f(\omega) \propto e^{-\sigma^2\omega^2/2}$, and it can be verified directly that:

• the variance of $\lvert f \rvert^2$ is $\sigma^2/2$, so $\Delta t = \sigma/\sqrt2$
• the variance of $\lvert \hat f \rvert^2$ is $1/(2\sigma^2)$, so $\Delta\omega = 1/(\sigma\sqrt2)$
• the product is exactly $1/2$

The parameter $\sigma$ can only transfer uncertainty between time and frequency; it cannot reduce the total. This is the theoretical basis for the choice of a Gaussian window in the Gabor transform.

2.4 Limiting Cases and Corollaries

The Paley–Wiener theorem further implies that no nonzero function is compactly supported in both the time domain and the frequency domain. This explains why finite-length filters necessarily possess a transition band.

3. Tiling of the Time-Frequency Plane

The geometric interpretation of the above constraint is that the area of each “resolution cell” in the time-frequency plane has a lower bound; different transforms merely tile the same plane with cells of different shapes.

• Time-domain sampling: the cell degenerates into a vertical strip spanning the full band, $\Delta t \to 0$, $\Delta f \to \infty$
• STFT / Gabor: the cell is a rectangle of fixed shape, with the same window length shared across the full band
• Wavelet transform: the cell shape dilates and contracts with scale. At scale $a$ the wavelet atom is $a^{-1/2}\psi\left(\frac{t-b}{a}\right)$; its time spread is proportional to $a$ and its frequency spread inversely proportional to $a$, so the product is independent of $a$

The cell areas of all three are subject to the same constraint $\Delta t\cdot\Delta f \geq 1/(4\pi)$. Wavelets do not break this constraint; they only redistribute resolution according to frequency. The precise origin of this lower bound in windowed analysis is the reproducing kernel of the transform’s range, i.e. the ambiguity function of the analysis window itself; see Section 4.3 for details.

4. Why Invertibility Does Not Provide Local Readability

4.1 Mechanism 1: Time Information Is Encoded in the Phase Slope

Consider the most extreme time-localised event, an instantaneous impulse $\delta(t-t_0)$, whose Fourier transform is

$$ \mathcal{F}[\delta(t-t_0)] (\omega) = e^{-i\omega t_0} $$

The magnitude spectrum is identically 1 and completely flat along the entire frequency axis. The information “the event occurs at $t_0$” is not lost at all, but it does not reside in any single frequency component; it exists in the form of the slope of the phase with respect to frequency:

$$ \frac{d\varphi}{d\omega} = -t_0 $$

Measuring the slope of a straight line requires a sufficiently long baseline in the independent variable. If the observation bandwidth is only $B$, then

$$ \delta t_0 \sim \frac{1}{B} $$

This is another face of the uncertainty principle: the time-localisation precision is determined by the span of observation in the frequency domain.

4.2 Mechanism 2: The Magnitude Spectrum Cannot Distinguish Temporal Order

Construct a pair of contrasting signals: $A(t)$ is a modulated signal that is low-frequency first and high-frequency afterwards, and $B(t) = A(t_{\rm end} - t)$ is its time reversal. By the time-reversal property of the Fourier transform, for real signals

$$ \hat B(\omega) = \overline{\hat A(\omega)} e^{-i\omega t_{\rm end}} \qquad\Longrightarrow\qquad \lvert \hat B(\omega) \rvert \equiv \lvert \hat A(\omega) \rvert $$

The magnitude spectra of the two are exactly equal point by point. However finely the frequency axis is subdivided, the magnitude spectrum cannot determine the order of events; the difference resides 100% in the phase. The inverse transform can of course distinguish the two perfectly, but this requires a global reconstruction using the complete phase over the full band at full precision; “reading off the instant at a glance from the spectrum” is a local read-out and is precisely the forbidden operation.

4.3 Mechanism 3: The Range of Windowed Analysis Is Constrained by a Reproducing Kernel

The preceding two subsections concern the ordinary Fourier transform. On passing to windowed analysis the operator properties change, and this change yields the sharpest formulation of the uncertainty principle in the time-frequency domain.

Let the window $g$ satisfy $\lVert g\rVert_2 = 1$. The short-time Fourier transform (with the $e^{-2\pi i t\omega}$ convention) is

$$ V_g f(b, \omega) = \int f(t) \overline{g(t-b)} e^{-2\pi i t\omega} dt $$

From the Moyal orthogonality relation

$$ \langle V_{g_1} f_1, V_{g_2} f_2\rangle_{L^2(\mathbb{R}^2)} = \langle f_1, f_2\rangle \overline{\langle g_1, g_2\rangle} $$

taking $g_1 = g_2 = g$ and $f_1 = f_2 = f$ gives $\lVert V_g f\rVert_{L^2(\mathbb{R}^2)} = \lVert f\rVert_{L^2(\mathbb{R})}$, so $V_g$ preserves the norm. However, $V_g$ maps functions of one variable to functions of two variables, so its range must be a proper closed subspace of $L^2(\mathbb{R}^2)$, and it cannot be surjective. Hence

$$ V_g^{\ast}V_g = I, \qquad V_g V_g^{\ast} = P \neq I $$

where $P$ is the orthogonal projection onto the range. $V_g$ is an isometry, not a unitary operator; unitarity requires a bijective isometry. The same holds for the continuous wavelet transform $W_\psi$.

Reproducing kernel of the range. The range is a reproducing kernel Hilbert space: every admissible time-frequency map $F = V_g f$ must satisfy the fixed-point equation

$$ F(z) = \int_{\mathbb{R}^2} F(z^{\prime}) \langle \pi(z^{\prime})g, \pi(z)g\rangle dz^{\prime} $$

where $\pi(z)$ is the time-frequency shift operator, and the modulus of the kernel $\lvert\langle \pi(z^{\prime})g, \pi(z)g\rangle\rvert = \lvert V_g g(z-z^{\prime})\rvert$ is exactly the ambiguity function of the window itself. This yields the precise formulation of the uncertainty principle in the STFT domain:

Every time-frequency map is a fixed point of convolution with the ambiguity function of the window, so its concentration cannot be finer than the time-frequency footprint of the window itself.

For a Gaussian window, the area of this footprint equals exactly the lower bound $1/(4\pi)$. The impossibility of drawing an arbitrarily sharp time-frequency map is not a deficiency of algorithms; a sharp map simply does not lie in the range.

Numerical verification. For a fully dense discrete Gabor system with $N = 64$, a Gaussian window and a hop of 1 ($V$ maps an $N$-dimensional vector to an $N\times N$ matrix), the results are as follows (code in Appendix A.1):

That is: more than 98% of the functions on the time-frequency plane are not the short-time Fourier transform of any signal.

After discretisation the STFT constitutes a Gabor frame, which is generally redundant; at critical density, the Balian–Low theorem (Reference 7) further shows that good time-frequency localisation and a Riesz basis cannot be obtained simultaneously.

4.4 An Intuitive Analogy

Suppose the traffic light at an intersection has a constant period of 60 s. After 1 h of continuous recording, an FFT shows a spectral line at $1/60 = 16.67\ \mathrm{mHz}$, and the inverse transform recovers the red/green state at any instant exactly. Here “both time and frequency are known” holds, not because the Fourier transform circumvents the uncertainty principle, but because the signal is stationary: the frequency does not change over time, so the problem of joint localisation is never posed.

Now consider an adaptive traffic light that switches at some instant from a 60 s period to a 40 s period, and pose the joint question: “What is the period, and when does it change?” Distinguishing the two periods requires a frequency resolution finer than

$$ \Delta f = \frac{1}{40} - \frac{1}{60} = 8.33\ \mathrm{mHz} $$

Even with an optimal Gaussian window, the theoretical lower bound $\Delta t \geq 1/(4\pi\Delta f)$ gives $\Delta t \geq 9.55\ \mathrm{s}$. The statement “the period changes from 60 s to 40 s, and the switch occurs within ±1 s of a certain instant” cannot hold simultaneously in mathematical terms, regardless of sampling rate, data volume or algorithmic sophistication.

5. Numerical Example: A Cross-Band Dual Task

5.1 Distinguishing Two Kinds of Constraint

Before discussing whether wavelets hold an advantage, two constraints of entirely different nature must be distinguished:

This yields the key to deciding whether wavelets can hold an advantage:

• When the two tasks lie in the same frequency band, they compete for the same resolution cell and must be served by the same atom, which runs into the physical constraint. The compatibility condition is then $\Delta t_{\rm sep}\cdot\Delta f_{\rm sep} \gtrsim 1/\pi$; if it is not satisfied, no method (including wavelets) has a solution.
• When the two tasks lie in two widely separated frequency bands, they are served by atoms of different scales, each of which only needs to satisfy the physical constraint individually, and the atoms do not compete. The failure of the STFT then stems purely from the artificial constraint, which wavelets remove by using different atoms for different frequencies.

The example constructed in this section belongs to the latter case.

5.2 Signal Design

A rotating-machinery fault-diagnosis scenario is adopted ($f_s = 10\ \mathrm{kHz}$, duration 2 s):

• Low-frequency task: the fundamental frequencies of two shafts, 24.0 Hz and 30.0 Hz ($\Delta f_{\rm sep} = 6\ \mathrm{Hz}$). Question: which shaft is unbalanced
• High-frequency task: 3000 Hz resonance impacts excited by a bearing defect, occurring at $t = 1.000\ \mathrm{s}$ and $t = 1.015\ \mathrm{s}$ ($\Delta t_{\rm sep} = 15\ \mathrm{ms}$). Question: when do the impacts occur

The two questions have the same form (“which one” and “when”), but their requirements on the analysis parameters point in opposite directions, and they lie in two frequency bands separated by a factor of 111.

The product $\Delta t_{\rm sep}\cdot\Delta f_{\rm sep} = 0.015 \times 6 = 0.090$ is below the single-atom dual-task threshold $1/\pi = 0.318$, so no STFT with a single window length has a solution; however, it exceeds the absolute lower bound $1/(4\pi) = 0.0796$, and the two tasks lie at different frequencies, so the problem is not forbidden by the physical constraint.

5.3 Analytical Feasible Region

The STFT must satisfy both requirements with a single window length. Using the Hann-window main-lobe width $2/T_{\rm win}$ as the resolution criterion:

$$ T_{\rm win} \geq \frac{2}{\Delta f_{\rm sep}} = 333\ \mathrm{ms} \quad\wedge\quad T_{\rm win} \leq \Delta t_{\rm sep} = 15\ \mathrm{ms} \quad\Longrightarrow\quad \text{feasible region} = \varnothing $$

The lower limit is 22 times the upper limit.

The free parameter of the CWT is the quality factor $Q$ ($Q = \omega_0$ for the Morlet wavelet). Under the amplitude convention, its resolution scales with frequency:

$$ \Delta f = \frac{f}{Q}, \qquad \sigma_t = \frac{Q}{2\pi f}, \qquad \sigma_t \cdot \Delta f = \frac{1}{2\pi}\ \text{(independent of frequency)} $$

The two requirements are imposed at their respective frequencies and therefore do not conflict:

$$ Q \geq \frac{2 f_L}{\Delta f_{\rm sep}} = \frac{2\times 27}{6} = 9.0 \quad\wedge\quad Q \leq \pi f_H \Delta t_{\rm sep} = \pi\times 3000\times 0.015 = 141 $$

$$ \Longrightarrow\quad \text{feasible region} = [9,\ 141] \neq \varnothing $$

With $Q = 24$, the actual resolutions are: at 27 Hz, $\Delta f = 1.12\ \mathrm{Hz} \ll 6\ \mathrm{Hz}$; at 3000 Hz, $\sigma_t = 1.27\ \mathrm{ms} \ll 15\ \mathrm{ms}$. Both requirements are met with ample margin.

5.4 Numerical Results

For each method a single full-band time-frequency map is given (logarithmic frequency axis, 180 ms time window), so that both tasks can be read simultaneously on the same map: cyan dashed lines mark 24 and 30 Hz, and green dashed lines mark 1.000 and 1.015 s.

The criterion is the Rayleigh dip-depth criterion: two main peaks are judged resolved only if the valley between them is below 0.7 times the peak value. This criterion excludes spurious double peaks caused by amplitude ripple.

Only the CWT column exhibits both features simultaneously: at the low-frequency end, two distinct spectral lines lie at 24 and 30 Hz, and at the high-frequency end, two distinct vertical lines lie at 1.000 and 1.015 s. Each of the three STFT window lengths fails in at least one task, and the direction of failure shifts monotonically with window length: the short window preserves time, the long window preserves frequency, and the intermediate window preserves neither.

In the quantitative slices, the CWT curve is the only one that exhibits a double peak in both the left and right panels.

5.5 Image Details and Methodological Points

First, the diffuse band spanning the full width at 3000 Hz in the 819 ms panel. The impact energy is spread over 819 ms, far beyond the 180 ms display window, so it appears as a uniform horizontal band rather than vertical lines. The information is not lost; only the time localisation is completely smeared out.

Second, the fine horizontal fringes in the high-frequency region of the 102 ms and 819 ms panels. The fringe spacing is $1/\Delta t_{\rm sep} = 66.7\ \mathrm{Hz}$; these are interference fringes of the two impacts. A window longer than the impact interval records “two impacts” as “one event plus frequency-domain fringes”, which is another encoding of the same fact.

Third, both descriptions are correct. The 12.8 ms window gives the description “a single 27 Hz component whose amplitude beats at 6 Hz” (beat period 167 ms, clearly visible in the time-domain waveform); the 819 ms window gives the description “two independent components at 24 and 30 Hz”. Both describe the same signal and neither is wrong. The uncertainty principle does not destroy information; it only determines the form in which the information is presented. This is the same phenomenon as discussed in Section 4.

Fourth, zero-padding does not improve resolution. In the decision computation all three window lengths are zero-padded to 16384 points, giving a uniform frequency grid of $f_s/N_{\rm FFT} = 0.61\ \mathrm{Hz}$, far finer than the 6 Hz spacing. The frequency slice of the 12.8 ms window is smooth and adequately sampled, yet still shows only a single peak. Resolution is determined by the window length and is independent of the number of FFT points; zero-padding merely performs sinc interpolation of the spectrum and introduces no new information.

6. General Criterion: The Feasible-Region Width Ratio

Let the two tasks lie at frequencies $f_L$ (requiring frequency resolution $\Delta f_{\rm sep}$) and $f_H$ (requiring time resolution $\Delta t_{\rm sep}$), with $f_H > f_L$. From the two expressions of Section 5.3, define the feasible-region width ratio

$$ R = \frac{Q_{\max}}{Q_{\min}} = \frac{\pi}{2}\cdot\frac{f_H}{f_L}\cdot \Delta t_{\rm sep}\cdot\Delta f_{\rm sep} \approx 1.571\ \frac{f_H}{f_L}\ \Delta t_{\rm sep}\ \Delta f_{\rm sep} $$

The decision rule is:

• $R < 1$: wavelets have no solution
• $R \approx 1$: the feasible region degenerates and the solution is not robust
• $R \gg 1$: the feasible region is ample and wavelets hold a robust advantage

Equivalently, a wavelet solution requires

$$ \frac{f_H}{f_L} \geq \frac{2}{\pi}\cdot\frac{1}{\Delta t_{\rm sep}\cdot\Delta f_{\rm sep}} \approx \frac{0.637}{\Delta t_{\rm sep}\cdot\Delta f_{\rm sep}} $$

Substituting the example of this article: $\Delta t_{\rm sep}\cdot\Delta f_{\rm sep} = 0.090$ requires $f_H/f_L \geq 7.1$, whereas the actual value is 111, so $R = 15.7$ with ample margin. For comparison, if the two tasks both lie near 100 Hz ($f_H/f_L \approx 2.9$) with $\Delta t_{\rm sep}\cdot\Delta f_{\rm sep} = 0.16$, then $R = 0.74 < 1$ and wavelets likewise have no solution; this is exactly the case of “competing for the same resolution cell” described in Section 5.1.

The expression shows that the larger the frequency ratio of the two tasks and the looser their respective resolution requirements, the wider the feasible region of wavelets. $R$ can be computed directly from the task specifications before the analysis scheme is designed, without trial computation.

7. Conclusions and Scope of Application

The advantage of wavelets is not that they “break the uncertainty principle”, but that they “remove the artificial constraint of the STFT sharing a single window across the full band”. On this basis a clear method-selection criterion can be given:

• Wavelets should be used when the signal has a multiscale structure, the low-frequency components require high frequency resolution, the high-frequency components require high time resolution, and $R \gg 1$. Typical scenarios include rotating-machinery fault diagnosis, joint analysis of seismic first arrivals and surface waves, analysis of the ST segment and QRS complex in ECG signals, and transient electromagnetic responses.
• Wavelets are unnecessary when all objects of interest lie in the same frequency band (the constant-$Q$ property then offers no benefit, and a long-window STFT is preferable), or when the signal itself is stationary (a direct FFT suffices).
• Wavelets also have no solution when $R < 1$, i.e. the two tasks compete for the same resolution cell. In this case one must turn to nonlinear methods such as synchrosqueezing or reassigned spectrograms, or change the sensing modality, for example recording events directly with timestamps; event records undergo no time-frequency decomposition and are therefore not subject to this constraint.

Appendix: Reproducible Code

The environment is Python 3.14 + NumPy 2.4 + SciPy 1.18.

A.1 Verification of Operator Properties (Section 4.3)

# -*- coding: utf-8 -*-"""The discrete STFT is an isometry but not a unitary operator"""import numpy as nprng = np.random.default_rng(7)N = 64k = np.arange(N)E = np.exp(-2j * np.pi * np.outer(k, k) / N)          # E[m, t] = exp(-2i pi m t / N)g = np.exp(-0.5 * ((k - N / 2) / (N / 8.0)) ** 2)g = g / np.linalg.norm(g)                              # unit-norm Gaussian windowG = np.stack([np.roll(g, j) for j in range(N)], axis=1)   # G[t, n] = g[t-n]def V(f):    """Discrete STFT: N-dim vector -> N x N complex matrix (rows: frequency, columns: time shift)"""    return E @ (f[:, None] * np.conj(G))def Vstar(F):    """Adjoint operator"""    return np.einsum("mn,mt,tn->t", F, np.conj(E), G)f1 = rng.standard_normal(N) + 1j * rng.standard_normal(N)f2 = rng.standard_normal(N) + 1j * rng.standard_normal(N)c = N * np.linalg.norm(g) ** 2r1 = np.linalg.norm(V(f1)) ** 2 / np.linalg.norm(f1) ** 2r2 = np.linalg.norm(V(f2)) ** 2 / np.linalg.norm(f2) ** 2print("norm  : {:.10f}  {:.10f}   theory N||g||^2 = {:.10f}".format(r1, r2, c))print("l-inv : ||V*Vf/c - f||/||f|| = {:.3e}".format(    np.linalg.norm(Vstar(V(f1)) / c - f1) / np.linalg.norm(f1)))R = rng.standard_normal((N, N)) + 1j * rng.standard_normal((N, N))   # arbitrary function on the time-frequency planePR = V(Vstar(R)) / cprint("onto  : ||PR - R||/||R||     = {:.4f}".format(    np.linalg.norm(PR - R) / np.linalg.norm(R)))print("idemp : ||P(PR) - PR||/||PR|| = {:.3e}".format(    np.linalg.norm(V(Vstar(PR)) / c - PR) / np.linalg.norm(PR)))F1 = V(f1)print("kernel: ||PF - F||/||F||     = {:.3e}".format(    np.linalg.norm(V(Vstar(F1)) / c - F1) / np.linalg.norm(F1)))print("dim range {} / dim ambient space {} = {:.2f}%".format(N, N * N, 100.0 * N / N ** 2))

A.2 Cross-Band Dual-Task Decision (Section 5.4)

The following script reproduces the analytical feasible region and the decision table of the main text, excluding the plotting part.

# -*- coding: utf-8 -*-"""Numerical decision for the cross-band dual taskLow-frequency task:  resolve the two shaft components at 24 / 30 Hz       -> requires a long windowHigh-frequency task: resolve two impacts 15 ms apart at 3000 Hz           -> requires a short windowConclusion: every single STFT window length fails; the Morlet wavelet succeeds for Q in [9, 141]."""import numpy as npfrom scipy.signal import ShortTimeFFTfrom scipy.signal.windows import hanndef stft_mag(x, fs, N, hop, mfft):    """Hann-window STFT magnitude. Zero-padded to mfft points so that the frequency grid is much finer than the resolution."""    S = ShortTimeFFT(hann(N, sym=False), hop=hop, fs=fs, mfft=mfft, scale_to="magnitude")    return np.abs(S.stft(x)), S.f, S.t(x.size)def cwt_morlet(x, fs, freqs, Q):    """Morlet continuous wavelet transform. Amplitude-preserving normalisation: a unit-amplitude sinusoid gives |W| = 1 at its own scale."""    Xf = np.fft.fft(x)    w = 2 * np.pi * np.fft.fftfreq(x.size, d=1 / fs)    pos = w > 0    out = np.empty((freqs.size, x.size))    for i, fc in enumerate(freqs):        a = Q / (2 * np.pi * fc)        out[i] = np.abs(np.fft.ifft(Xf * (2.0 * np.exp(-(a * w - Q) ** 2 / 2) * pos)))    return outdef resolved(y, thr=0.5, dip=0.7):    """Rayleigh dip-depth criterion: two main peaks are judged resolved only if the valley between them is below dip times the peak value."""    idx = [i for i in range(1, len(y) - 1)           if y[i] > y[i - 1] and y[i] >= y[i + 1] and y[i] > thr]    if len(idx) < 2:        return False    a, b = sorted(sorted(idx, key=lambda i: -y[i])[:2])    return y[a:b + 1].min() <= dip * min(y[a], y[b])def nrm(v):    return v / v.max()# ---------------------------------------------------------------- signal constructionfs = 10000.0t = np.arange(0, 2.0, 1 / fs)FL1, FL2, FH = 24.0, 30.0, 3000.0      # fundamental frequencies of the two shafts; bearing resonance frequencyTH1, TH2 = 1.000, 1.015                # instants of the two impactsDF, DT = FL2 - FL1, TH2 - TH1          # 6 Hz; 15 msFL = 0.5 * (FL1 + FL2)x = np.sin(2 * np.pi * FL1 * t) + np.sin(2 * np.pi * FL2 * t)for t0 in (TH1, TH2):    m = t >= t0    x[m] += 2.5 * np.exp(-(t[m] - t0) / 6e-4) * np.sin(2 * np.pi * FH * (t[m] - t0))x += 0.01 * np.random.default_rng(1).standard_normal(t.size)# ---------------------------------------------------------------- analytical feasible regionT_LO = 2.0 / DF                 # STFT low-frequency task: Hann main lobe 2/T_win <= df_sepT_HI = DT                       # STFT high-frequency task: T_win <= dt_sepQ_MIN = 2 * FL / DF             # CWT low-frequency task: 2*Df = 2*f_L/Q <= df_sepQ_MAX = np.pi * FH * DT         # CWT high-frequency task: 2*sigma_t = 2*Q/(2*pi*f_H) <= dt_sepQ_USE = 24.0print("ratio f_H/f_L = {:.0f},  dt_sep * df_sep = {:.3f}".format(FH / FL, DT * DF))print("STFT: T_win >= {:.0f} ms and T_win <= {:.0f} ms  ->  empty set (factor {:.0f})"      .format(T_LO * 1e3, T_HI * 1e3, T_LO / T_HI))print("CWT : Q >= {:.1f} and Q <= {:.1f}  ->  [{:.0f}, {:.0f}], R = {:.1f}, use Q = {:.0f}"      .format(Q_MIN, Q_MAX, Q_MIN, Q_MAX, Q_MAX / Q_MIN, Q_USE))print("Q = {:.0f}: at {:.0f} Hz Df = {:.2f} Hz;  at {:.0f} Hz sigma_t = {:.2f} ms\n"      .format(Q_USE, FL, FL / Q_USE, FH, Q_USE / (2 * np.pi * FH) * 1e3))# ---------------------------------------------------------------- numerical decisionLO, HI = (15.0, 40.0), (2000.0, 4000.0)rows = []for N in (128, 1024, 8192):    S, f, tt = stft_mag(x, fs, N, hop=20, mfft=16384)    fm = (f >= LO[0]) & (f <= LO[1])    r1 = resolved(nrm(S[fm, int(np.argmin(np.abs(tt - 0.60)))]))    bm = (f >= HI[0]) & (f <= HI[1])    env = nrm(np.sqrt((S[bm] ** 2).mean(axis=0)))    tm = (tt >= 0.97) & (tt <= 1.05)    rows.append(("STFT {:.0f} ms".format(N / fs * 1e3), r1, resolved(env[tm])))    del Sfreqs = np.geomspace(15.0, 4200.0, 340)W = cwt_morlet(x, fs, freqs, Q=Q_USE)lom = (freqs >= LO[0]) & (freqs <= LO[1])him = (freqs >= HI[0]) & (freqs <= HI[1])r1 = resolved(nrm(W[lom, int(np.argmin(np.abs(t - 0.60)))]))env = nrm(np.sqrt((W[him] ** 2).mean(axis=0)))tm = (t >= 0.97) & (t <= 1.05)rows.append(("CWT Q={:.0f}".format(Q_USE), r1, resolved(env[tm])))print("{:<14s}{:>10s}{:>10s}{:>9s}".format("method", "low-f", "high-f", "dual"))print("-" * 46)for name, r1, r2 in rows:    print("{:<14s}{:>10s}{:>10s}{:>9s}".format(        name, "resolved" if r1 else "merged", "resolved" if r2 else "merged",        "pass" if (r1 and r2) else "fail"))print("-" * 46)print("methods passing both tasks: {}".format(sum(1 for _, a, b in rows if a and b)))

References

1. Gabor D. Theory of communication. Journal of the Institution of Electrical Engineers, 1946, 93(26): 429–457.
2. Folland G B, Sitaram A. The uncertainty principle: a mathematical survey. Journal of Fourier Analysis and Applications, 1997, 3(3): 207–238.
3. Daubechies I. Ten Lectures on Wavelets. Philadelphia: SIAM, 1992.
4. Mallat S. A Wavelet Tour of Signal Processing: The Sparse Way. 3rd ed. Burlington: Academic Press, 2008.
5. Torrence C, Compo G P. A practical guide to wavelet analysis. Bulletin of the American Meteorological Society, 1998, 79(1): 61–78.
6. Donoho D L, Stark P B. Uncertainty principles and signal recovery. SIAM Journal on Applied Mathematics, 1989, 49(3): 906–931.
7. Benedetto J J, Heil C, Walnut D F. Differentiation and the Balian–Low theorem. Journal of Fourier Analysis and Applications, 1995, 1(4): 355–402.
8. Daubechies I, Lu J, Wu H-T. Synchrosqueezed wavelet transforms: an empirical mode decomposition-like tool. Applied and Computational Harmonic Analysis, 2011, 30(2): 243–261.
9. Douyin video. https://v.douyin.com/YxlCjq6-NnI/

The page is adapted to mobile devices and is best viewed in portrait orientation.

1 Project Background

The original firmware of the WHEELTEC mecanum chassis exhibits a stop failure: the encoder feedback is constantly 0, the static variables of the incremental PI controller are never reset, and stop commands therefore have no effect. This project modifies the STM32 firmware to address the problem and builds a complete multimodal control system on the RK3588:

• Web-based remote control: HTTP + MJPEG streaming; the robot can be operated from any browser
• Embedded firmware fix: an emergency-stop flag is added to resolve the stop failure
• Thermal imaging acquisition: Hikvision HM-TD2028T-7, outputting a 256×192 temperature matrix
• Real-time IMU monitoring: on-board SH3001 six-axis sensor
• USB camera: real-time MJPEG video stream

2 Hardware List

3 Network Architecture

WiFi hotspot (any hotspot; name and password are configured in start.py)        │        ├── 📱 Phone / tablet   → open http://RK3588_IP:8080 in a browser        ├── 💻 Computer         → open http://RK3588_IP:8080 in a browser        └── 🤖 RK3588          → runs the Flask control service :8080                  │                  ├── wlan0  joins the hotspot (control traffic)                  └── eth0   192.168.1.100 (connected to the thermal camera)                                    │                                thermal camera 192.168.1.64

When an iPhone hotspot is used, the board IP is fixed at 172.20.10.3 (the iPhone hotspot subnet is fixed); for other hotspots, the actually assigned IP applies.

4 Project Structure

rk3588-multimodal-mecanum/├── README.md├── host/                          ← run on the PC during first deployment│   ├── start.py                   ← one-click launcher ★ (edit hotspot name/password)│   ├── connect_wifi.py            ← reconnect WiFi separately│   └── motor_web/                 ← services pushed to the RK3588 and run in the background│       ├── server.py              ← Flask control server (main program)│       └── daemon.py              ← daemon wrapper│├── firmware/                      ← complete STM32 Keil project (compiles directly)│   ├── USER/Template.uvprojx      ← open with Keil μVision 5│   ├── BALANCE/CONCTRL/│   │   ├── conctrl.c              ← ★ modified: emergency-stop mechanism added│   │   └── conctrl.h              ← ★ modified: exports the Emergency_Stop variable│   ├── HAREWARE/                  ← peripheral drivers│   ├── CORE/                      ← startup files│   ├── STM32F10x_FWLib/           ← ST official standard peripheral library│   └── SYSTEM/│├── thermal/                       ← thermal imaging acquisition (deployed to RK3588)│   ├── thermal_save_local.py      ← main temperature-matrix acquisition script ★│   ├── thermal_matrix_sdk.py      ← SDK snapshot + appended-data approach│   ├── thermal_sdk_probe.py       ← data-format diagnostic tool│   └── thermal_fps_test.c         ← frame-rate test in C (requires cross-compilation)│└── imu/                           ← IMU monitoring (deployed to RK3588)    ├── sh3001_monitor.py          ← real-time SH3001 six-axis monitoring    └── sh3001_calib.example.json  ← example calibration file

5 Quick Start

5.1 Configuring the WiFi Hotspot

The only configuration that must be modified in the entire project is the hotspot name and password, and it appears in only two files.

Open host/start.py and modify lines 18-19:

# host/start.pySSID     = "Huawei 14 Pro 暗夜紫"   # ← replace with the hotspot namePASSWORD = "00000000"               # ← replace with the hotspot password

Modify lines 18-19 of host/connect_wifi.py in the same way (used when reconnecting WiFi separately):

# host/connect_wifi.pySSID     = "Huawei 14 Pro 暗夜紫"PASSWORD = "00000000"

server.py, daemon.py and all other files require no changes.

5.2 First Launch (Pushing the Service over USB)

Connect the RK3588 via USB, then run on the PC:

python host/start.py

The script automatically performs the following steps:

1. Detects the ADB USB connection
2. Connects the RK3588 to the configured hotspot
3. Pushes the control service to the board
4. Starts the Flask server
5. Opens the browser

The USB cable is required only for the first launch or when the service is updated; it can be unplugged afterwards.

5.3 Accessing the Control Page from Any Device

Any device on the same hotspot can open the following address directly in a browser:

http://172.20.10.3:8080

6 Control Page Layout

The web page is adapted to mobile touch screens and uses a four-panel layout:

┌──────────────────┬──────────────────┐│   ⚙ Motor Control│  📡 Sensor Data  ││  ↖  ↑  ↗        │  Accel  Gyro     ││  ←  ■  →        │  Mag    Vibration││  ↙  ↓  ↘        │                  │├──────────────────┼──────────────────┤│  📷 USB Camera   │   🌡 Thermal      ││  Live MJPEG feed │  Pseudo-color map│└──────────────────┴──────────────────┘

Motor control mode (tap to toggle):

• Tap a direction key once → the robot starts moving
• Tap the same key again / tap ■ → the robot stops
• To change direction, tap the new direction key directly
• The robot stops automatically when the page is moved to the background

7 Embedded Firmware (STM32)

7.1 Key Modification: Emergency-Stop Mechanism

Stop commands have no effect in the original WHEELTEC firmware. The core change is located in BALANCE/CONCTRL/conctrl.c:

// Global variableu8 Emergency_Stop = 0;// Inside TIM6_IRQHandlerif(Move_X == 0 && Move_Y == 0 && Move_Z == 0) {    Emergency_Stop = 1;          // Trigger emergency stop    smooth_control.VX = 0;    smooth_control.VY = 0;    smooth_control.VZ = 0;} else {    Emergency_Stop = 0;    Drive_Motor(Move_X, Move_Y, Move_Z);}// One line added at the beginning of every Incremental_PI functionif(Emergency_Stop) { Pwm=0; Bias=0; Last_bias=0; return 0; }

7.2 Compiling and Flashing

1. Open firmware/USER/Template.uvprojx with Keil μVision 5
2. Press F7 to compile
3. Flash firmware/USER/OBJ/Template.hex with FlyMcu
   • Before flashing: set BOOT0 to 1 and press the reset button
   • After flashing: set BOOT0 back to 0 and press the reset button

7.3 Communication Protocol

The RK3588 sends 11-byte binary frames over USB-CDC (/dev/ttyACM0, 115200 baud):

7B 00 [Vx_H Vx_L] [Vy_H Vy_L] [Vz_H Vz_L] 00 [XOR] 7DVx = forward/backward velocity (mm/s, int16 big-endian)  range ±500Vy = lateral translation (mm/s, int16 big-endian)        range ±500Vz = rotational velocity (mm/s, int16 big-endian)        range ±1500

Mecanum kinematics (inverse solution):

$$
\begin{aligned}
FL &= V_y + V_x - V_z \
FR &= -V_y + V_x + V_z \
RL &= V_y + V_x + V_z \
RR &= -V_y + V_x - V_z
\end{aligned}
$$

8 Thermal Imaging (Hikvision HM-TD2028T-7)

8.1 Connection

Thermal camera ──Ethernet cable──▶ RK3588 eth0IP: 192.168.1.64                   IP: 192.168.1.100Username: adminPassword: hk159753Requires an external 12V power supply (USB power is not permitted)

8.2 Acquisition Script

adb push thermal/thermal_save_local.py /userdata/hik_vision_project/# First run (configures camera parameters)adb shell python3 /userdata/hik_vision_project/thermal_save_local.py --config --bench# Normal acquisition afterwardsadb shell python3 /userdata/hik_vision_project/thermal_save_local.py

Output (local to the RK3588):

/tmp/thermal/latest.npy     ← float32 matrix, 256×192, unit °C/tmp/thermal/latest.json    ← max/min/mean/hotspot coordinates

Frame-rate upper limit: ~3 fps (a hardware limitation; the official documentation states “1-4 images per second; real-time frame rates cannot be achieved”)

9 Six-Axis IMU (SH3001)

adb push imu/sh3001_monitor.py /root/adb shell python3 /root/sh3001_monitor.py  # The first run performs zero-bias calibration

10 Frequently Asked Questions

Q: How is the hotspot changed?

Only the two lines SSID and PASSWORD at the top of host/start.py and host/connect_wifi.py need to be changed.

Q: The page is not fully displayed when controlling from a phone

The page is adapted to mobile devices; landscape orientation gives a better result.

Q: The hotspot connection times out

Verify the hotspot name, which is case-sensitive; for a Chinese hotspot name, ensure the encoding is correct (copying and pasting the name is recommended).

Q: What is the IP of the RK3588?

start.py prints it at runtime. For an iPhone hotspot it is fixed at 172.20.10.3; for other hotspots, the printed value applies.

Q: The IP changed after switching hotspots; how is the connection made?

Re-run python host/start.py; it prints the new IP and opens the browser.

Q: The motors do not stop

Confirm that the modified firmware (firmware/BALANCE/CONCTRL/conctrl.c) has been flashed.

Q: The thermal image is not displayed

Check that: ① the Ethernet cable is plugged in; ② the thermal camera is powered by 12V; ③ adb shell ping 192.168.1.64 succeeds

Q: Is USB required after updating the service?

Yes. After server.py is modified, python host/start.py must be run once over USB to push the service again; the cable can be unplugged afterwards.

11 Technology Stack

12 Project Repository

GitHub: https://github.com/Yu-Xiang-Yang/rk3588-multimodal-mecanum

Related reading:

• One-Click Deployment of Python Applications on RK3588 with Autostart at Boot
• Tutorial on Connecting and Using a Camera with the RK3588 Edge-Computing Chip (in Chinese)

Stars and issues are welcome.

1 Background and Problems

The RK3588 is a high-performance edge-computing chip. Running Python applications on its Buildroot system typically involves the following problems:

• No network access on the device: pip install cannot be used directly, so dependencies must be installed offline
• Tedious deployment steps: every code update requires a manual adb push and a service restart
• Complex autostart configuration: an init.d script must be written by hand and its permissions set

This project automates these steps so that they are completed with a single command.

2 Project Structure

├── deploy.sh               # One-click deployment script (Git Bash)├── deploy.ps1              # One-click deployment script (PowerShell)├── download_packages.sh    # Automatic download of offline dependencies (Git Bash)├── download_packages.ps1   # Automatic download of offline dependencies (PowerShell)├── S99rk3588app            # init.d autostart service script└── app/    ├── main.py             # Application entry point (replace with the actual application)    ├── requirements.txt    # Python dependency list (optional)    └── packages/           # Offline .whl dependency packages (downloaded automatically)

3 Prerequisites

• The RK3588 device is connected via USB and is recognised by adb devices
• Python3 is installed on the device (/usr/bin/python3)
• The host environment is Windows (PowerShell / Git Bash) or Linux/macOS

4 Quick Start

4.1 Cloning the Project

git clone https://github.com/Yu-Xiang-Yang/deploy.gitcd deploy

4.2 Adding the Application

Place the Python program in the app/ directory and name the entry file main.py.

Example app/main.py:

import timewhile True:    print("test", flush=True)    time.sleep(10)

Note: print requires flush=True; otherwise the log is not written in real time when the program runs in the background.

4.3 One-Click Deployment

PowerShell (recommended):

.\deploy.ps1

If a script execution policy restriction is reported, run the following once first:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Git Bash:

bash deploy.sh

The script automatically performs the following steps:

1. Checks the ADB connection
2. Stops the old service
3. Uploads all files under app/ to /data/rk3588app/ on the device
4. Installs offline dependency packages (if .whl files exist under app/packages/)
5. Installs the autostart script to /etc/init.d/S99rk3588app
6. Starts the service and verifies it

4.4 Verifying the Deployment

# Check the service statusadb shell /etc/init.d/S99rk3588app status# View the logadb shell cat /data/rk3588app/app.log

5 Offline Installation of Python Dependencies

RK3588 devices usually have no network access, so .whl files must be downloaded on a computer in advance.

5.1 Automatic Download (Recommended)

Create requirements.txt under app/ and list the dependencies:

requestsnumpy==1.26.4

Run the download script, which automatically downloads the .whl files matching the RK3588 architecture (aarch64 + Python 3.10):

PowerShell:

.\download_packages.ps1

Git Bash:

bash download_packages.sh

After the download completes, run the deployment script; the dependencies are then uploaded to and installed on the device automatically.

5.2 Manual Download

The .whl files can also be downloaded manually and placed in app/packages/:

pip download <package_name> --platform linux_aarch64 --python-version 310 --only-binary=:all: -d app/packages/

If pip download cannot find a package for the target platform, the .whl file for cp310-linux_aarch64 can be downloaded manually from PyPI.

5.3 Version Compatibility Issues

Some older package versions may not provide aarch64 prebuilt files, in which case the download reports an error:

ERROR: No matching distribution found for psutil==5.8.0

Solution: change == to >= in requirements.txt to allow a newer compatible version to be downloaded:

psutil>=5.8.0

In general, pure-Python packages (such as pyserial and six) are not platform-restricted, whereas packages with C extensions (such as numpy and psutil) require checking whether the given version provides aarch64 prebuilt files.

6 Common Commands

7 Custom Configuration

To change the deployment path or service name, edit the variables at the top of deploy.sh (or deploy.ps1):

REMOTE_APP_DIR="/data/rk3588app"      # Application directory on the deviceSERVICE_NAME="S99rk3588app"           # Service script name (a larger number starts later)

The corresponding path in S99rk3588app must be changed accordingly.

8 Principle

The RK3588 Buildroot system manages boot-time services with init.d. Scripts under /etc/init.d/ whose names begin with S are executed in numerical order at system startup.

8.1 Core Logic of the Autostart Script

S99rk3588app uses start-stop-daemon to run the Python program as a background process and redirects stdout/stderr to a log file:

case "$1" in  start)    printf "Starting rk3588app: "    sleep 3    start-stop-daemon -S -b -m -p $PIDFILE \      --exec /bin/sh -- -c "exec $DAEMON $SCRIPT >> $LOGFILE 2>&1"    echo "OK"    ;;  stop)    printf "Stopping rk3588app: "    start-stop-daemon -K -p $PIDFILE    rm -f $PIDFILE    echo "OK"    ;;esac

8.2 Startup Order

The number following S in the script name determines the startup order; smaller numbers are executed earlier:

S00mountall.sh   → mount file systemsS10udev          → device managementS40network       → networkS50sshd          → SSH serviceS99rk3588app     → user application (started last)

S99 ensures that the application starts only after system services such as networking and serial ports are ready. For an earlier start, the number can be reduced (e.g. S50rk3588app), but retaining S99 is generally recommended.

9 Project Repository

GitHub: https://github.com/Yu-Xiang-Yang/deploy

Stars and issues are welcome.