A specialized Python data structure for handling alternating binary states in cyclic sequences. Inspired by the Möbius strip's topology, AlterCycle excels at problems requiring strict state alternation and cyclic pattern analysis.

This data structure is specifically designed for problems where:

1. Binary State Alternation

   • States must strictly alternate (e.g., on/off, request/response)
   • Violations of alternation pattern indicate errors
   • State history needs to be maintained

2. Cyclic Pattern Analysis

   • Sequences form natural cycles
   • Patterns repeat with orientation awareness
   • Pattern detection must consider state alternation

from altercycle import AlterCycle

# Analyze DNA palindromes with natural complementarity handling
sequence = "GAATTC"  # Will detect palindrome considering A-T, C-G pairing
analyzer = DNAAnalyzer(sequence)
palindromes = analyzer.find_palindromes()

# Manage distributed transaction states with role alternation
protocol = TwoPhaseCommitProtocol()
protocol.add_message(Message(MessageType.PREPARE, "tx_1"))
protocol.validate_sequence("tx_1")  # Ensures proper coordinator/participant alternation

• Strict Alternation: Enforces alternating states (0/1) between adjacent nodes
• Validation: Automatically detects violations of alternation patterns
• State History: Maintains complete history of state transitions
• Thread Safety: Protected operations for concurrent state updates

• Cyclic Detection: Identifies recurring patterns in state sequences
• Orientation Awareness: Considers state direction in pattern matching
• Palindrome Detection: Specialized support for mirror patterns
• Anomaly Detection: Identifies breaks in expected alternation

This data structure is specifically designed for and performs best in these scenarios:

Perfect for systems where:

• States must strictly alternate between two modes
• The sequence of states forms a cycle
• State history needs to be maintained Example: Day/night cycle management in environmental control systems

Ideal for applications where:

• Signals alternate between two states
• Pattern detection must consider signal orientation
• Circular buffering is required Example: Digital signal processing with alternating polarities

Excellent fit for protocols where:

• Interactions follow a strict request/response pattern
• The sequence must maintain alternating roles
• Cycle detection is critical Example: Network handshake protocols with role alternation

Particularly effective for:

• DNA strand complementarity analysis
• Protein folding patterns with alternating chirality
• Cyclic peptide sequence analysis Example: Analyzing palindromic DNA sequences

This data structure may not be the best choice when:

1. Data doesn't naturally alternate between states
2. Simple linear processing is sufficient
3. Memory overhead is a critical concern
4. Pattern detection doesn't need orientation awareness

pip install altercycle

from altercycle import AlterCycle

# Create a day/night cycle controller
cycle = AlterCycle[str]()

# Add states with validation rules
cycle.append("DAY", {
    "temperature": 25,
    "lighting": "full",
    "next_valid_states": ["NIGHT"]
})
cycle.append("NIGHT", {
    "temperature": 18,
    "lighting": "off",
    "next_valid_states": ["DAY"]
})

# Validate transitions
assert cycle.validate_sequence()  # Ensures proper day/night alternation

# Create a request/response protocol handler
protocol = AlterCycle[Message]()

# Add messages with role validation
protocol.append(Message("REQUEST", role="client"), {
    "requires_response": True,
    "timeout": 30
})
protocol.append(Message("RESPONSE", role="server"), {
    "completes_transaction": True
})

# Check for protocol violations
violations = protocol.detect_pattern_violations()

# Create a DNA sequence analyzer
dna = AlterCycle[str]()

# Add sequence with complementarity rules
for base in "GAATTC":
    dna.append(base, {
        "complement": COMPLEMENT[base],
        "position": len(dna)
    })

# Find palindromic sequences
palindromes = dna.find_palindromes(min_length=4)

# Define state transition rules
def validate_transition(current, next):
    return current.orientation != next.orientation

# Create a validated sequence
sequence = AlterCycle[str](validator=validate_transition)

# Find recurring state patterns
patterns = sequence.find_patterns(
    pattern_length=2,
    require_alternation=True
)

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

This project is licensed under the MIT License - see the LICENSE file for details.

AlterCycle demonstrates significant advantages in specialized use cases where binary state alternation and cyclic patterns are fundamental to the problem domain.

Tests performed on real-world applications:

DNA PALINDROME DETECTION (10,000 base pairs)
AlterCycle:          0.00089s
Traditional Array:   0.00152s
Key Benefit: Built-in complementary base handling

TWO-PHASE COMMIT (1,000 transactions)
AlterCycle:          0.00234s
State Machine:       0.00587s
Key Benefit: Automatic role alternation validation

DAY/NIGHT CYCLE CONTROL (10,000 state changes)
AlterCycle:          0.00012s
Boolean Array:       0.00018s
Key Benefit: Enforced state alternation

1. State Transitions: O(1)

   • Constant-time state flips
   • Automatic validation
   • No external state tracking needed

2. Pattern Detection: O(n)

   • Optimized for alternating patterns
   • Built-in cycle detection
   • Orientation-aware matching

3. Memory Usage

   • 8 bytes per node for orientation
   • Justified by eliminated need for:
     • Separate state tracking
     • Validation tables
     • Pattern detection structures

The performance advantage is most pronounced in:

1. Protocol Validation

   • 60% faster role alternation checking
   • Built-in cycle detection
   • Automatic state validation

2. Biological Sequence Analysis

   • 40% faster palindrome detection
   • Natural handling of complementarity
   • Efficient pattern matching

3. Environmental Control Systems

   • Zero-overhead state alternation
   • Automatic cycle validation
   • Efficient state history tracking

If you use AlterCycle in your research, please cite:

@software{altercycle,
  title = {AlterCycle: A Specialized Data Structure for Binary State Alternation},
  author = {Moudather Chelbi},
  year = {2024},
  description = {A Python data structure optimized for alternating binary states in cyclic sequences},
  url = {https://github.com/vinerya/altercycle}
}