ChELL’s Physical Filesystem Mode (--physicalFS) provides a fallback mode that operates directly on physical ChRIS storage paths without logical-to-physical path mapping. This is useful for debugging, direct storage access, and performance optimization when link resolution is not needed.
ChRIS uses a logical-to-physical path mapping system where:
-
Logical paths are what users see and navigate (e.g.,
/home/user/public/data) -
Physical paths are where data actually resides (e.g.,
/SHARED/dataifpublicis a link)
While the PathMapper singleton optimizes this with hierarchical prefix caching, there are scenarios where:
-
Direct access is needed - Working directly with physical storage paths
-
Debugging is required - Seeing actual storage structure without abstraction
-
Links don’t exist - No symbolic links in the filesystem to resolve
-
Performance is critical - Eliminating even optimized mapping overhead
Start chell with physical mode enabled:
chell --physicalFSOr with connection parameters:
chell --physicalFS --user alice --password pass123 http://cube.example.com/api/v1/Toggle physical mode during a session:
# Check current status
physicalmode
# Enable physical mode
physicalmode on
# Disable physical mode
physicalmode off# User navigates to logical path
cd /home/user/public/data
# ChELL resolves to physical location
# Internal: /home/user/public -> /SHARED (link)
# Validation checks: /SHARED/data
# CWD stored as: /home/user/public/data (logical)# User navigates using links or physical paths
cd /home/user/public/data
# ChELL resolves links directly
# Resolves: /home/user/public -> /PUBLIC (link)
# Validation checks: /PUBLIC/data
# CWD stored as: /PUBLIC/data (resolved physical path)
# Note: No PathMapper caching, just direct link resolutionWhen logical paths aren’t resolving correctly:
# Start in physical mode
chell --physicalFS
# Navigate directly to physical storage
cd /SHARED
# See actual directory structure
ls
# Check if data exists at physical location
cat /SHARED/important-file.txtWorking with physical storage paths from documentation or logs:
# Physical path from log file: /STORAGE/uploads/batch_123/data.csv
chell --physicalFS
cd /STORAGE/uploads/batch_123
ls
cat data.csvWhen processing thousands of files without links:
# No links exist, skip mapping overhead
chell --physicalFS
cd /raw_data/experiment_2025
# Process many files without path resolution overheadThe context command shows the current physical mode status:
contextOutput:
┌─────────────────────────────────────────────────────────┐
│ ChRIS Context │
├───────────────┬─────────────────────────────────────────┤
│ Context │ Value │
├───────────────┼─────────────────────────────────────────┤
│ ChRIS User │ rudolphpienaar │
│ ChRIS URL │ http://cube.example.com/api/v1/ │
│ ChRIS Folder │ /SHARED/data │
│ ChRIS Feed │ Not set │
│ ChRIS Plugin │ Not set │
│ Physical Mode │ Enabled │ ← Status shown
└───────────────┴─────────────────────────────────────────┘Physical mode is controlled by a boolean flag in the Session singleton:
// Session class
class Session {
private _physicalMode: boolean = false;
physicalMode_get(): boolean {
return this._physicalMode;
}
physicalMode_set(enabled: boolean): void {
this._physicalMode = enabled;
}
}In builtin_cd():
let validationPath: string;
if (session.physicalMode_get()) {
// Physical mode: use path directly
validationPath = logicalPath;
} else {
// Logical mode: resolve logical → physical
const { logical_toPhysical } = await import('@fnndsc/chili/utils');
const physicalResult = await logical_toPhysical(logicalPath);
validationPath = physicalResult.value;
}
// Validate path exists
await client.getFileBrowserFolderByPath(validationPath);| Operation | API Calls |
|---|---|
First path resolution |
O(depth) |
Repeated exact path |
0 (cache hit) |
Path with cached prefix |
O(new components) |
| Operation | API Calls |
|---|---|
Any path resolution |
0 (no resolution) |
Directory validation |
1 (existence check only) |
When to use Physical Mode:
-
No performance benefit if links exist and PathMapper is warm
-
Small benefit if links exist but cache is cold
-
Significant benefit if no links exist (avoids all resolution overhead)
Physical mode does follow links, but does not use PathMapper’s hierarchical caching:
# Both modes resolve links:
cd /home/user/public
# Resolves: public -> /PUBLIC ✓ (works in both modes)
# Difference is in how they resolve:
# Logical mode: Uses PathMapper with hierarchical prefix caching
# Physical mode: Direct link resolution without caching overhead
# Example with nested paths:
cd /home/user/public/feed_4
# Logical: PathMapper caches /home/user/public -> /PUBLIC for future reuse
# Physical: Resolves public -> /PUBLIC but doesn't cache the mappingPaths in physical mode are not portable across environments with different storage layouts:
# Environment A physical path
cd /STORAGE/shared/data
# Environment B might use different physical structure
cd /mnt/nfs/shared/data # Different path!Physical paths are less intuitive for end users:
-
Logical:
/home/alice/public/data✓ (clear, user-centric) -
Physical:
/STORAGE/UUID-1234/uploads/data✗ (opaque, system-centric)
-
Debugging: "Why isn’t this path resolving?"
-
System administration: Direct storage management
-
Performance testing: Benchmarking without mapper overhead
-
Emergency access: When mapping system has issues
Cause: Using logical path in physical mode.
Solution:
# Option 1: Switch to logical mode
physicalmode off
cd /home/user/public/data # Works with links
# Option 2: Use physical path
physicalmode on
cd /SHARED/data # Direct physical pathCause: Mode was set via CLI flag before session initialization.
Solution: Toggle mode to refresh prompt:
physicalmode off
physicalmode onCause: Logical path includes unresolved links.
Solution: Find physical path first:
# In logical mode session
physicalmode off
cd /home/user/public/data
pwd # Note this path
# Check context to see actual folder
context
# Physical path shown in "ChRIS Folder"-
PathMapper Implementation - Logical-to-physical mapping optimization
-
ChELL Architecture - Overall system design
-
ChELL Login and Session Management - Session state management
Added: 2025-01-31
Author: Claude + User collaboration
Status: ✅ Implemented and documented