Validation Module¶

Input validation and system state checking.

ChemstationAPI.controllers.validation.ValidationModule ¶

ValidationModule(communicator: ChemstationCommunicator)

Comprehensive validation and system state checking for ChemStation operations.

Provides validation methods for all aspects of ChemStation operation including file system validation, instrument state checking, vial management validation, and method execution verification. All validation methods follow consistent patterns and raise specific exceptions for different failure modes.

Validation Philosophy

Fail fast: Detect problems before they cause system errors
Specific exceptions: Different failure modes have different exception types
Case-insensitive: File and method name checking handles case variations
Comprehensive checking: Validate all prerequisites before operations

File System Validation

Method file existence in ChemStation directories
Sequence file existence and accessibility
Case-insensitive filename matching
Path validation and accessibility checking

Instrument State Validation

System readiness for operations
Carousel availability and operational state
Method execution state verification
Error condition detection and reporting

Vial Management Validation

Individual vial presence checking
Batch vial validation for sequences
Position occupancy verification
Carousel state comprehensive monitoring

Attributes:

Name	Type	Description
`comm`		ChemStation communicator for validation queries.

Initialize validation module with ChemStation communicator.

Parameters:

Name	Type	Description	Default
`communicator`	`ChemstationCommunicator`	ChemStation communication interface for validation queries.	required

Functions¶

validate_sequence_name ¶

validate_sequence_name(sequence: str, dir_path: str = '_SEQPATH$') -> None

Validate that sequence file exists in specified directory.

Performs case-insensitive validation of sequence file existence in the ChemStation sequence directory. This prevents errors when loading sequences with different case variations in filenames.

Parameters:

Name	Type	Description	Default
`sequence`	`str`	Sequence name (without .S extension). Examples: "protein_analysis", "DAILY_QC", "Method_Development"	required
`dir_path`	`str`	Path to sequence directory. Defaults to ChemStation sequence directory (_SEQPATH$). Can specify custom path.	`'_SEQPATH$'`

Raises:

Type	Description
`ValidationError`	If sequence file doesn't exist in specified directory. Error message includes actual directory path for debugging.
`FileNotFoundError`	If sequence directory doesn't exist or isn't accessible.

Examples:

Validate before loading:

>>> validation.validate_sequence_name("Protein_Analysis")
>>> seq.load_sequence("Protein_Analysis")  # Safe to load

Validate custom directory:

>>> validation.validate_sequence_name("TestSeq", "C:\Custom\Sequences\")

Note

Case-insensitive matching (protein_analysis matches Protein_Analysis.S)
Automatically appends .S extension for checking
Validates directory accessibility before file checking
Essential for preventing sequence loading failures

validate_method ¶

validate_method(method: str, dir_path: str = '_METHODPATHS$', check_vials: bool = False) -> None

Validate that CE method file exists in specified directory.

Parameters:

Name	Type	Description	Default
`method`	`str`	Method name (without .M extension).	required
`dir_path`	`str`	Path to method directory. Defaults to _METHPATH$.	`'_METHODPATHS$'`
`check_vials`	`bool`	If True, also validates that method's vials are in carousel.	`False`

Raises:

Type	Description
`ValidationError`	If method file doesn't exist.
`VialError`	If check_vials=True and required vials are missing.

validate_vials_in_method ¶

validate_vials_in_method(method: str = '_METHFILE$', dir_path: str = '_METHODPATHS$') -> None

Validate that all vials required by the method are present in carousel.

Parameters:

Name	Type	Description	Default
`method`	`str`	Method name (without .M extension) or "_METHFILE$" for currently loaded method.	`'_METHFILE$'`
`dir_path`	`str`	Path to method directory. Defaults to _METHODPATHS$.	`'_METHODPATHS$'`

Raises:

Type	Description
`VialError`	If required vials are missing from carousel.

validate_vial_in_system ¶

validate_vial_in_system(vial: int) -> None

Validate that specified vial is present somewhere in the CE system.

Checks that a vial is physically present in the CE system, either in the carousel or loaded at one of the lift positions. This prevents operations on missing vials that would cause instrument errors.

Parameters:

Name	Type	Description	Default
`vial`	`int`	Vial position number to check (1-50). Position 49 is typically reserved for replenishment parking.	required

Raises:

Type	Description
`VialError`	If vial is not detected anywhere in the system. This indicates the vial is missing or not properly seated.
`SystemError`	If unable to query vial state from instrument.

Examples:

Validate before loading:

>>> validation.validate_vial_in_system(15)
>>> ce.load_vial_to_position(15, "inlet")  # Safe to load

Validate sample list:

>>> sample_vials = [10, 11, 12, 15, 20]
>>> for vial in sample_vials:
...     validation.validate_vial_in_system(vial)

Note

Checks all possible vial locations (carousel + lift positions)
State "4" (out_system) indicates vial not detected
Essential before any vial manipulation operations
Prevents instrument errors from missing vials

validate_method_run ¶

validate_method_run() -> None

Validate that method execution started successfully.

Checks the ChemStation _MethodOn system variable to verify that method execution actually started after a run command. This catches method startup failures that would otherwise go undetected.

Raises:

Type	Description
`MethodError`	If method is not running, indicating startup failure. This could be due to instrument not ready, parameter errors, or system conflicts.

Examples:

Validate after method start:

>>> method.run("Sample001")
>>> validation.validate_method_run()  # Confirm it started

Use in automated workflows:

>>> try:
...     method.execution_method_with_parameters(15, "CE_Method", "Sample")
...     validation.validate_method_run()
...     print("Method started successfully")
... except MethodError:
...     print("Method failed to start - check instrument status")

Note

Should be called shortly after method start commands
_MethodOn=1 indicates successful method execution
Essential for detecting silent method startup failures
Allows early detection of configuration problems

vial_in_position ¶

vial_in_position(position: str) -> None

Validate that a vial is loaded at the specified lift position.

Checks that a vial is actually present at the specified lift position before operations that require vial contact (injection, electrode contact). This prevents operations that would fail due to missing vials.

Parameters:

Name	Type	Description	Default
`position`	`str`	Lift position to check. Valid positions: - "inlet": Sample injection position - "outlet": Waste/collection position - "replenishment": Buffer replenishment position	required

Raises:

Type	Description
`VialError`	If no vial is loaded at the specified position.
`ValueError`	If invalid position is specified.

Examples:

Check before injection:

>>> validation.vial_in_position("inlet")
>>> ce.apply_pressure_to_capillary(50.0, 5.0)  # Safe injection

Verify setup before analysis:

>>> validation.vial_in_position("inlet")   # Sample vial
>>> validation.vial_in_position("outlet")  # Waste vial
>>> method.run("Analysis")  # Safe to run

Note

Essential before operations requiring vial contact
Lift must have vial loaded, not just carousel presence
Different from vial_in_system which checks any location
Prevents electrode contact failures and injection errors

validate_use_carousel ¶

validate_use_carousel(num_attempt=3) -> None

Validate that carousel is available for vial operations.

Checks the CE instrument RC status to ensure the carousel system is available for vial loading/unloading operations. This prevents carousel operations during incompatible instrument states.

Parameters:

Name	Type	Description	Default
`num_attempt`	`int`	Number of validation attempts before raising error. Default is 2. Each attempt is separated by 2 second delay.	`3`

Raises:

Type	Description
`SystemError`	If carousel is not available for use after all attempts. This occurs during method execution, error states, or maintenance modes that lock carousel access.

Examples:

Check before vial operations with default attempts:

>>> validation.validate_use_carousel()
>>> ce.load_vial_to_position(15, "inlet")  # Safe to load

Check with custom number of attempts:

>>> validation.validate_use_carousel(num_attempt=5)
>>> ce.load_vial_to_position(15, "inlet")  # Safe to load

Validate before batch operations:

>>> validation.validate_use_carousel()
>>> for vial in vial_list:
...     ce.load_vial_to_position(vial, "inlet")

Note

"Idle" state allows carousel operations
"Run" state may allow limited carousel access
Other states (Error, Maintenance) block carousel use
Function waits 1 second between validation attempts
Essential before any automated vial handling

get_vialtable ¶

get_vialtable() -> Dict[int, bool]

Get comprehensive status of all carousel positions.

Queries the CE instrument for the presence status of all 48 carousel positions and returns a dictionary mapping position numbers to presence status. This provides a complete overview of vial distribution.

Returns:

Type	Description
`Dict[int, bool]`	Dictionary mapping position numbers (1-48) to boolean presence status.
`Dict[int, bool]`	True indicates vial is present (in carousel or at lift position),
`Dict[int, bool]`	False indicates position is empty.

Raises:

Type	Description
`VialError`	If vial table cannot be read from instrument.
`SystemError`	If communication with carousel system fails.

Examples:

Get complete vial overview:

>>> vial_table = validation.get_vialtable()
>>> occupied_positions = [pos for pos, present in vial_table.items() if present]
>>> print(f"Vials present at positions: {occupied_positions}")

Check specific positions:

>>> vial_table = validation.get_vialtable()
>>> for pos in [10, 11, 12]:
...     if vial_table[pos]:
...         print(f"Vial at position {pos} ready")

Find empty positions:

>>> vial_table = validation.get_vialtable()
>>> empty_positions = [pos for pos, present in vial_table.items() if not present]

Note

Includes positions 1-48 (position 49 handled separately)
True means vial detected (any location in system)
Useful for sequence planning and vial management
Updates reflect real-time carousel status

list_vial_validation ¶

list_vial_validation(vials: list) -> None

Validate that all vials in list are present in carousel system.

Performs batch validation of multiple vials for sequence operations or batch analysis. This ensures all required vials are present before starting automated workflows that would fail on missing vials.

Parameters:

Name	Type	Description	Default
`vials`	`list`	List of vial position numbers to validate. Examples: [1, 2, 3], [10, 15, 20, 25], range(1, 49)	required

Raises:

Type	Description
`VialError`	If any vials are missing from the carousel. Error message lists all missing vial positions for easy identification and correction.

Examples:

Validate sequence vials:

>>> sequence_vials = [10, 11, 12, 15, 20]
>>> validation.list_vial_validation(sequence_vials)
>>> # Safe to start sequence with these vials

Validate range of positions:

>>> validation.list_vial_validation(list(range(1, 25)))  # Check 1-24

Handle validation errors:

>>> try:
...     validation.list_vial_validation([1, 2, 3, 4, 5])
... except VialError as e:
...     print(f"Missing vials: {e}")
...     # Load missing vials before continuing

Note

Efficient batch checking using single carousel query
Reports all missing vials simultaneously
Essential before sequence execution
Prevents partial sequence failures due to missing vials

extract_vials_from_xml ¶

extract_vials_from_xml(method_path)

Extract vial numbers from CE method XML configuration file.

Parses ChemStation CE method XML files to extract all vial position numbers referenced in the method configuration. This includes vials used for inlet/outlet positions, preconditioning programs, injection programs, and any other method operations requiring vial access.

Parameters:

Name	Type	Description	Default
`method_path`	`str`	Path to the CE method directory (.M folder). Function automatically looks for the standard "AgilentCEDriver1.RapidControl.MethodXML.xml" file within this directory.	required

Returns:

Name	Type	Description
`list`		Sorted list of unique vial position numbers (integers). Only positive vial numbers are included (negative values like -1 are filtered out as they represent "no vial" conditions). Empty list if no valid vials found or file reading fails.

Examples:

Extract vials from method:

>>> vials = extract_vials_from_xml("C:/Methods/CE_Protein.M")
>>> print(f"Method requires vials: {vials}")
[1, 5, 6, 7]

Use with method validation:

>>> method_dir = os.path.join(methods_path, "CE_Protein.M")
>>> required_vials = extract_vials_from_xml(method_dir)
>>> validation.list_vial_validation(required_vials)

Note

Automatically constructs path to AgilentCEDriver1.RapidControl.MethodXML.xml
File is read with UTF-16 encoding (ChemStation XML standard)
Searches for all tags in the XML
Automatically filters negative vial numbers (-1, etc.)
Returns empty list on file read errors (with error message printed)
Essential for method vial dependency validation before execution