neuralqx.utils.errors module#

Custom neuraLQX errors implementation

exception neuralqxError(msg)#: Bases: Exception

exception neuralqxWarning(msg, stack_level=2)#: Bases: Warning

exception GraphUnavailableWarning(stack_level=2)#: Bases: neuralqxWarning

exception DeniedExperimentalFeatureError(name)#: Bases: neuralqxError

exception DeniedExperimentalModuleImportError#: Bases: neuralqxError

exception IncompatibleNonGIOperatorError#: Bases: neuralqxError

exception InvalidSurfaceError(s_type)#: Bases: neuralqxError

exception InvalidIndexError(edge)#: Bases: neuralqxError

exception InvalidChargeError(charge, cutoff)#: Bases: neuralqxError

exception InvalidCutoffError(dtype_cutoff, dtype_step)#: Bases: neuralqxError

exception InvalidMelsFunctionError#: Bases: neuralqxError

exception IncompatibleJaxOperatorError(op_type)#: Bases: neuralqxError

exception InvalidOperatorsSequenceError(func)#: Bases: neuralqxError

exception InvalidOperatorsInSequenceError(func)#: Bases: neuralqxError

exception InvalidEdgeSelectionError(num_edges, size)#: Bases: neuralqxError

exception InvalidFreeEdgeSelectionError(num_edges, num_free)#: Bases: neuralqxError

exception IncorrectEdgeFormatError#: Bases: neuralqxError

exception IncorrectMonitoringValueError(name, avail)#: Bases: neuralqxError

exception IncorrectGaugeFixingArrayError(reason)#: Bases: neuralqxError

exception NonHermitianInverseCostError#: Bases: neuralqxError

exception AutoConstraintGaugeFixingConflictError#: Bases: neuralqxError

exception DistributedStateImportMismatchError(mismatch_type, saved_data, current_data)#: Bases: neuralqxError

exception OutOfRangeIndexError(index, max_index)#: Bases: neuralqxError

exception CrossProductInHigherDimensionsError#: Bases: neuralqxError

exception DistributedStateImportInSerialModeError(n_nodes, ranks_per_node)#: Bases: neuralqxError

exception DistributedRuntimeUnavailableWarning(stack_level=2)#: Bases: neuralqxWarning

exception AreaDifferenceEdgesError(num_edges)#: Bases: neuralqxError

exception DuplicateEdgesError#: Bases: neuralqxError

exception OrientationValenceMismatchError(valence, orientation_len)#: Bases: neuralqxError

exception AreaDifferenceSurfacesError(num_edges)#: Bases: neuralqxError

exception ExpectationValueError(func)#: Bases: neuralqxError

exception MissingPenaltyFactorError#: Bases: neuralqxError

exception NonExistentNonPlanarEdgesError#: Bases: neuralqxError

exception NonExistentNonPlanarVerticesError#: Bases: neuralqxError

exception ExceededDtypeValuesError(dtype)#: Bases: neuralqxError

exception CyclicGaugeFixingError#: Bases: neuralqxError

exception AcceptanceUnavailableError(name)#: Bases: neuralqxError

exception UnspecifiedGaugeFixingError#: Bases: neuralqxError

exception HilbertSpaceGaugeGroupDimensionsMismatchError#: Bases: neuralqxError

exception IncompatibleNonPlanarGraphModel#: Bases: neuralqxError

exception IncompatiblePlanarGraphModel#: Bases: neuralqxError

exception IncompatibleHilbertSpaceError(available, required)#: Bases: neuralqxError

exception IncompatibleModdedOperatorWarning(stack_level=2)#: Bases: neuralqxWarning

exception RandomEmbeddingForPlanarGraphWarning(stack_level=2)#: Bases: neuralqxWarning

exception LiveMonitoringUnavailableWarning(stack_level=2)#: Bases: neuralqxWarning

exception ComputationalModelConcretizationWarning(stack_level=2)#: Bases: neuralqxWarning

exception SuboptimalOperatorForGPUWarning(stack_level=2)#: Bases: neuralqxWarning

exception StructError(msg)#

Bases: neuralqxError

Base exception for the struct and pytree subsystem.

This is the root error type for public APIs in neuralqx.utils.struct, including class processing, runtime validation, and serialization workflows.

exception FrozenStructError(msg)#

Bases: StructError, AttributeError

Raised when mutation is attempted on a frozen Struct instance.

Struct instances are immutable after initialisation. Direct attribute writes and deletions are rejected to preserve deterministic pytree and cache semantics. Use obj.replace(...) to derive updated instances.

exception SerializationError(msg)#

Bases: StructError

Raised when struct or registered-pytree I/O operations fail.

Typical causes include:

unsupported value types without registered adapters,
malformed or version-incompatible payloads,
array manifest mismatches (missing arrays, dtype/shape drift),
class/adaptor resolution failures during reconstruction.

exception ValidationError(msg)#

Bases: StructError, TypeError

Raised when declarations or runtime values violate struct constraints.

Typical causes include:

invalid field declaration combinations,
non-hashable/static-array violations for static fields,
validator failures on field assignment/finalisation.

exception SymbolicOperatorDefinitionError(msg)#

Bases: neuralqxError

Raised when a symbolic operator is constructed with invalid DSL declarations.

Typical causes include empty term lists, unsupported iterator kinds, unresolvable symbol references, or invalid amplitude/predicate expressions.

exception SymbolicOperatorExecutionError(msg)#

Bases: neuralqxError

Raised when a symbolic operator is called before it has been compiled.

Symbolic operators cannot execute until lowered through SymbolicCompiler.compile(); calling get_conn_padded on an uncompiled symbolic operator raises this error.

exception SymbolicOperatorIRValidationError(msg)#

Bases: neuralqxError

Raised when symbolic operator IR fails structural or semantic validation.

Typical causes include unbound site-label references, invalid update-op parameters, or globally-iterated terms that reference site DOFs.

exception SymbolicCompilerError(msg)#

Bases: neuralqxError

Raised when the symbolic compiler pipeline encounters an unrecoverable error.

This is the top-level error for compilation failures including pass errors, lowering failures, and cache-layer errors. Inspect the message for the specific failure stage and cause.