System Module¶

System monitoring and status management.

ChemstationAPI.controllers.system_module.SystemModule ¶

SystemModule(communicator: ChemstationCommunicator)

System monitoring and diagnostic control for ChemStation CE operations.

Provides comprehensive system status monitoring, method execution tracking, and diagnostic capabilities for the CE instrument. Essential for automated workflows, user interfaces, and system diagnostics.

Key monitoring capabilities include real-time acquisition status tracking, method execution state monitoring, analysis timing information, and instrument readiness validation.

Diagnostic Tools

Register browser for system debugging and parameter inspection
Error condition monitoring and emergency abort capabilities
System readiness validation with timeout handling
Performance timing analysis for optimization

RC Status Integration

Direct access to RC.NET status registers provides detailed instrument status including run states, error conditions, and operational modes for comprehensive system monitoring.

Attributes:

Name	Type	Description
`comm`		ChemStation communicator for system command execution and status queries

Initialize system monitoring module with ChemStation communicator.

Parameters:

Name	Type	Description	Default
`communicator`	`ChemstationCommunicator`	ChemStation communication interface for status queries and system command execution	required

Functions¶

method_on ¶

method_on() -> bool

Check if an analytical method is currently executing.

Monitors ChemStation's _MethodOn system variable to determine if any analysis is actively running. Covers all method phases including preconditioning, injection, separation, detection, and postconditioning.

Returns:

Type	Description
`bool`	True if a method is currently executing (any phase), False if idle

Examples:

>>> # Wait for method completion
>>> while system.method_on():
...     print("Analysis in progress...")
...     time.sleep(30)
>>> 
>>> # Check before starting new analysis
>>> if not system.method_on():
...     api.method.run("NewSample")

Note

Essential for automation workflows to prevent overlapping analyses. Use with status() for detailed phase information.

status ¶

status() -> str

Get current ChemStation acquisition status.

Returns detailed acquisition status from ChemStation's ACQSTATUS$ system variable, providing specific information about the current operational state and analysis phase.

Returns:

Type	Description
`str`	Current acquisition status:
`str`	"STANDBY": System idle, ready for new analysis
`str`	"PRERUN": Pre-analysis conditioning and preparation
`str`	"RUN": Active separation and detection phase
`str`	"POSTRUN": Post-analysis conditioning and cleanup
`str`	"ERROR": Error condition requiring attention
`str`	"ABORT": Analysis aborted or interrupted

Examples:

>>> # Monitor analysis phases
>>> status = system.status()
>>> if status == "RUN":
...     print("Separation in progress")
>>> elif status == "STANDBY":
...     print("Ready for new sample")
>>> 
>>> # Wait for specific phase
>>> while system.status() != "RUN":
...     time.sleep(5)

Note

Status updates in real-time. STANDBY indicates readiness for new analysis. Includes automatic retry logic for communication reliability.

RC_status ¶

RC_status(module: str = 'CE1') -> str

Get current RC.NET module status for detailed instrument monitoring.

Queries RC.NET status registers for detailed instrument status including run states, error conditions, and operational modes. Provides more granular status information than basic acquisition status.

Parameters:

Name	Type	Description	Default
`module`	`str`	RC.NET module identifier. Default "CE1" for CE instrument. Other modules: "DAD1" (detector), "PUMP1", etc.	`'CE1'`

Returns:

Type	Description
`str`	Current RC module run state:
`str`	"Idle": Module ready and available for operations
`str`	"Run": Module actively executing operations
`str`	"NotReady": Module initializing or in error state
`str`	"Error": Module error condition requiring attention
`str`	"Maintenance": Module in maintenance mode

Examples:

>>> # Monitor CE instrument status
>>> if system.RC_status("CE1") == "Idle":
...     print("CE instrument ready")
>>> 
>>> # Check multiple modules
>>> for module in ["CE1", "DAD1"]:
...     print(f"{module}: {system.RC_status(module)}")

Note

More detailed than acquisition status. Useful for troubleshooting and system diagnostics. Includes automatic retry logic.

ready_to_start_analysis ¶

ready_to_start_analysis(modules=['CE1', 'DAD1'], timeout=None, verbose=True)

Wait for all specified modules to reach ready state for analysis.

Monitors multiple RC.NET modules until all reach "Idle" state with no "NotReady" conditions. Essential for ensuring instrument readiness before starting automated analysis sequences.

The function continuously polls module status and displays real-time progress when verbose mode is enabled. Modules must have both RunState="Idle" and empty NotReadyState_Description to be considered ready.

Parameters:

Name	Description	Default
`modules`	List of module identifiers to check (default: ["CE1", "DAD1"]) Common modules: "CE1" (capillary electrophoresis), "DAD1" (detector)	`['CE1', 'DAD1']`
`timeout`	Maximum waiting time in seconds. None = wait indefinitely Typical values: 10s (quick check), 60s (standard), 300s (long methods)	`None`
`verbose`	Display real-time status updates during waiting (default: True)	`True`

Returns:

Type	Description
	None (function returns when all modules ready)

Raises:

Type	Description
`TimeoutError`	If modules not ready within specified timeout period

Examples:

>>> # Quick readiness check before analysis
>>> system.ready_to_start_analysis(timeout=10, verbose=False)
>>> 
>>> # Wait for CE and detector with status updates
>>> system.ready_to_start_analysis(["CE1", "DAD1"], timeout=60)
>>> 
>>> # Wait indefinitely with progress display
>>> system.ready_to_start_analysis(verbose=True)

Note

Displays progress in top menu bar area when verbose=True. Modules must be both "Idle" and have no NotReady conditions to pass validation.

add_register_reader ¶

add_register_reader(register_reader_macro: str = 'ChemstationAPI\\controllers\\macros\\register_reader.mac') -> None

Add comprehensive register inspection tool to ChemStation Debug menu.

Add a powerful register browser tool in ChemStation's top menu bar that enables interactive inspection and modification of ChemStation registers. Invaluable for debugging, system analysis, advanced parameter editing, and understanding ChemStation's internal data structures.

The register browser provides a user-friendly interface for exploring complex register hierarchies including RC.NET objects, sequence tables, method parameters, and system variables.

Register Browser Features

Browse all ChemStation registers (RC.NET, sequence, method, system)
Inspect object structures and data tables interactively
View and modify header values and text fields
Navigate complex register hierarchies with tree view
Export register contents for analysis

Parameters:

Name	Type	Description	Default
`register_reader_macro`	`str`	Path to register reader macro file. Default uses included comprehensive register_reader.mac	`'ChemstationAPI\\controllers\\macros\\register_reader.mac'`

Examples:

>>> # Add register browser with default comprehensive tool
>>> system.add_register_reader()
>>> 
>>> # Use custom register reader
>>> system.add_register_reader("C:\Custom\debug_tools.mac")

Usage

After execution, look for "Show Registers" item in ChemStation's Debug menu (top menu bar). Tool provides full register browsing capabilities for advanced users and developers.

Note

Tool remains available until ChemStation restart. Exercise caution when modifying system registers as changes affect instrument operation.

abort_run ¶

abort_run() -> None

Immediately abort current analysis or sequence execution.

Sends emergency abort command to ChemStation that immediately terminates the current analysis, sequence, or operation. Used for emergency stops, error recovery, or when immediate termination is required.

The abort process immediately stops the current analysis phase, disables high voltage and pressure systems, and returns the instrument to a safe idle state. All method execution flags are cleared.

Raises:

Type	Description
`SystemError`	If abort command fails to execute

Examples:

>>> # Emergency stop
>>> system.abort_run()
>>> 
>>> # Conditional abort on error detection
>>> if error_detected:
...     system.abort_run()
...     print("Analysis aborted due to error")

Warning

Results in immediate termination without post-run conditioning. Data up to abort point may be saved. Instrument requires manual return to ready state after abort.

wait_for_ready ¶

wait_for_ready(timeout: int = 60) -> bool

Wait for ChemStation to reach ready state for new analysis.

Continuously polls system status until it reaches a state ready for new analysis (STANDBY or PRERUN) or until timeout expires. Essential for automated workflows that need to wait for instrument availability between analyses.

Parameters:

Name	Type	Description	Default
`timeout`	`int`	Maximum waiting time in seconds. Default 60 seconds. Increase for methods with long post-run conditioning. Typical values: 60s (standard), 300s (long methods), 600s (very long)	`60`

Returns:

Type	Description
`bool`	True if system reaches ready state within timeout,
`bool`	False if timeout expires before ready state achieved

Examples:

>>> # Standard workflow with timeout
>>> if system.wait_for_ready():
...     api.method.run("NextSample")
... else:
...     print("Timeout - check instrument status")
>>> 
>>> # Extended wait for long conditioning methods
>>> if system.wait_for_ready(timeout=300):  # 5 minutes
...     start_next_analysis()
>>> 
>>> # Sequence automation
>>> for sample in sample_list:
...     if system.wait_for_ready(timeout=120):
...         process_sample(sample)

Note

Polls status every second to minimize system load. Both STANDBY and PRERUN are considered ready states. Returns immediately if already ready.

get_elapsed_analysis_time ¶

get_elapsed_analysis_time() -> float

Get elapsed separation time since current analysis started.

Returns the time elapsed since the actual separation phase began in the current analysis. Excludes pre-run conditioning, injection, and preparation phases - measures only electrophoretic separation runtime.

Returns:

Type	Description
`float`	Elapsed separation time in minutes as float. Returns 0.0 if no
`float`	analysis is running or separation hasn't started yet.

Examples:

>>> # Monitor analysis progress
>>> elapsed = system.get_elapsed_analysis_time()
>>> total = system.get_analysis_time()
>>> progress = (elapsed / total) * 100
>>> print(f"Analysis {progress:.1f}% complete")
>>> 
>>> # Real-time monitoring with updates
>>> while system.method_on():
...     elapsed = system.get_elapsed_analysis_time()
...     print(f"Running for {elapsed:.2f} minutes")
...     time.sleep(30)

Note

Measures only separation phase, not total method time including conditioning. Updates in real-time with precision to 0.01 minutes.

get_analysis_time ¶

get_analysis_time() -> float

Get total expected separation duration for current method.

Returns the programmed separation duration from the currently loaded method's stoptime parameter. This represents the expected separation runtime and is used for progress calculations and time estimation.

Returns:

Type	Description
`float`	Total separation duration in minutes as float

Examples:

>>> # Calculate remaining time
>>> total_time = system.get_analysis_time()
>>> elapsed_time = system.get_elapsed_analysis_time()
>>> remaining = total_time - elapsed_time
>>> print(f"Analysis completes in {remaining:.2f} minutes")
>>> 
>>> # Check method duration before starting
>>> duration = system.get_analysis_time()
>>> if duration > 60:  # More than 1 hour
...     confirm = input(f"Long analysis ({duration:.1f}min). Continue? ")

Note

Based on method's programmed stoptime parameter. Does not include conditioning or injection time. Remains constant during execution.

get_remaining_analysis_time ¶

get_remaining_analysis_time() -> float

Get remaining separation time until current analysis completes.

Calculates time remaining until separation phase completes by subtracting elapsed time from total expected duration. Provides real-time countdown for analysis completion and progress monitoring.

Returns:

Type	Description
`float`	Remaining separation time in minutes as float. Returns 0.0 if no
`float`	analysis running. May be negative if analysis exceeds expected duration.

Examples:

>>> # Display countdown
>>> remaining = system.get_remaining_analysis_time()
>>> print(f"Analysis completes in {remaining:.1f} minutes")
>>> 
>>> # Progress monitoring with updates
>>> while system.method_on():
...     remaining = system.get_remaining_analysis_time()
...     if remaining > 0:
...         print(f"Time remaining: {remaining:.2f} minutes")
...     time.sleep(60)
>>> 
>>> # Automated scheduling
>>> if system.get_remaining_analysis_time() < 5:  # Less than 5 minutes
...     prepare_next_sample()

Note

Updates continuously during analysis. Useful for progress bars and time estimation in automated workflows.