# knitout_interpreter.knitout_execution_structures package

## Submodules

- knitout_interpreter.knitout_execution_structures.Carriage_Pass module
  - `Carriage_Pass`
    - `Carriage_Pass.instruction_set()`
    - `Carriage_Pass.rightward_sorted_needles()`
    - `Carriage_Pass.leftward_sorted_needles()`
    - `Carriage_Pass.sorted_needles()`
    - `Carriage_Pass.instructions_by_needles()`
    - `Carriage_Pass.carriage_pass_range()`
    - `Carriage_Pass.rack_instruction()`
    - `Carriage_Pass.direction`
    - `Carriage_Pass.needles`
    - `Carriage_Pass.first_instruction`
    - `Carriage_Pass.last_instruction`
    - `Carriage_Pass.last_needle`
    - `Carriage_Pass.contains_instruction_type()`
    - `Carriage_Pass.add_instruction()`
    - `Carriage_Pass.compatible_with_pass_type()`
    - `Carriage_Pass.can_add_instruction()`
    - `Carriage_Pass.can_merge_pass()`
    - `Carriage_Pass.merge_carriage_pass()`
    - `Carriage_Pass.execute()`
    - `Carriage_Pass.__str__()`
    - `Carriage_Pass.__list__()`
    - `Carriage_Pass.__len__()`
    - `Carriage_Pass.__repr__()`
    - `Carriage_Pass.__iter__()`
    - `Carriage_Pass.__getitem__()`
    - `Carriage_Pass.__hash__()`

## Module contents

knitout_execution_structures: Data structures for organizing knitout execution.

This module provides specialized data structures that organize knitout instructions into meaningful execution units. These structures bridge the gap between individual knitout instructions and the actual execution patterns on knitting machines.

Key Concepts:
  Carriage Pass: A sequence of instructions that can be executed in a single pass of the knitting machine carriage.

    Instructions in a carriage pass share common properties like direction, racking, and carrier usage.

  Organization: Instructions are automatically grouped into carriage passes based on machine constraints and execution efficiency. This organization is crucial for accurate timing analysis and machine operation.

Core Components:

  - Carriage_Pass: Main data structure representing a carriage pass

  - Pass organization and merging logic

  - Execution timing and analysis capabilities

  - Needle range and width calculations

Machine Execution Model:

  Real knitting machines operate in carriage passes rather than individual instructions. A carriage pass represents one sweep of the carriage across the needle bed, during which multiple operations can occur simultaneously.

  Pass Properties:

    - Direction: Leftward or rightward carriage movement

    - Racking: Bed alignment for the entire pass

    - Carriers: Yarn carriers active during the pass

    - Needle Range: Leftmost to rightmost needles involved

Example

Working with carriage passes from execution:

    >>> from knitout_interpreter.knitout_execution import Knitout_Executer
    >>> from knitout_interpreter.knitout_language.Knitout_Parser import  parse_knitout
    >>> from knitout_interpreter.knitout_execution_structures.Carriage_Pass import Carriage_Pass
    >>> from virtual_knitting_machine.Knitting_Machine import Knitting_Machine
    >>>
    >>> instructions = parse_knitout('knit + f1 1')
    >>> executer = Knitout_Executer(instructions, Knitting_Machine())
    >>> for i, carriage_pass in enumerate(executer.carriage_passes):
    ...     print(f"Pass {i+1}: {carriage_pass}")

Analyzing pass properties:

    >>> # Get timing and width information
    >>> execution_time = len(executer.carriage_passes)  # Number of passes
    >>> left, right = carriage_pass.carriage_pass_range()
    >>> width = right - left + 1
    >>> print(f"Passes over {width} needles from position {left} to {right}")

Pass Organization Rules:

  Instructions are grouped into carriage passes based on: - Execution direction (leftward/rightward) - Racking requirements (bed alignment) - Carrier usage (which yarns are active) - Instruction compatibility (can execute simultaneously) - Machine constraints (needle accessibility, timing)

Technical Implementation Details:

  Carriage_Pass.py: Main implementation of carriage pass data structure

  Pass Organization Algorithm:

    1. Instructions are processed sequentially

    2. Compatible instructions are grouped into the same pass

    3. Incompatible instructions start a new pass

    4. Passes are automatically ordered for machine execution

  Compatibility Rules:

    Instructions can share a carriage pass if they have: - Same execution direction - Same racking requirements - Same carrier usage - Compatible instruction types - Non-overlapping needle positions

Performance Considerations:

  - Pass organization is O(n) where n is the number of instructions

  - Memory usage scales with the number of unique carriage passes

class knitout_interpreter.knitout_execution_structures.Carriage_Pass(first_instruction, rack, all_needle_rack)

  Bases: `object`

  Manages knitout operations that are organized in a single carriage pass.

  instruction_set()

    Get an unordered set of the instructions in the carriage pass.

    Returns:

      An unordered set of the instructions in the carriage pass.

    Return type:

      set[Needle_Instruction]

  rightward_sorted_needles()

    Get needles sorted from left to right.

    Returns:

      List of needles in the carriage pass sorted from left to right.

    Return type:

      list[Needle]

  leftward_sorted_needles()

    Get needles sorted from right to left.

    Returns:

      List of needles in the carriage pass sorted from right to left.

    Return type:

      list[Needle]

  sorted_needles()

    Get needles sorted by carriage pass direction.

    Returns:

      List of needles in carriage pass sorted by direction of carriage pass or from left to right if no direction is given.

    Return type:

      list[Needle]

  instructions_by_needles(needles)

    Get instructions ordered by the given needle list.

    Parameters:

      needles (list[Needle]) – Ordered list of needles involved in the carriage pass.

    Returns:

      The ordered set of instructions that start from the given needles.

    Return type:

      list[Needle_Instruction]

  carriage_pass_range()

    Get the leftmost and rightmost needle positions in the carriage pass.

    Returns:

      Tuple of (leftmost position, rightmost position) in the carriage pass.

    Return type:

      tuple[int, int]

  rack_instruction(comment='Racking for next carriage pass.')

    Create a racking instruction to set up this carriage pass.

    Parameters:

      comment (str) – Comment to include with the racking instruction.

    Returns:

      Racking instruction to set up this carriage pass.

    Return type:

      Rack_Instruction

  property direction: Carriage_Pass_Direction | None

    Get or set the direction of the carriage pass.

    Setting the direction will reorder the instructions to the given direction. Should only be used to reorder Xfer Passes.

    Returns:

      The direction of the carriage pass.

  property needles: list[Needle]

    Get needles in the order given by instruction set.

    Returns:

      Needles in order given by instruction set.

  property first_instruction: Needle_Instruction

    Get the first instruction given to carriage pass.

    Returns:

      First instruction given to carriage pass.

  property last_instruction: Needle_Instruction

    Get the last instruction executed in the carriage pass.

    Returns:

      Last instruction executed in the given carriage pass.

  property last_needle: Needle

    Get the needle at the end of the ordered instructions.

    Returns:

      Needle at the end of the ordered instructions.

  contains_instruction_type(instruction_type)

    Check if the carriage pass contains a specific instruction type.

    Parameters:

      instruction_type (Knitout_Instruction_Type) – Instruction type to consider.

    Returns:

      True if the instruction type is used at least once in this carriage pass.

    Return type:

      bool

  add_instruction(instruction, rack, all_needle_rack)

    Attempt to add an instruction to the carriage pass.

    Parameters:

      - instruction (Needle_Instruction) – The instruction to attempt to add to the carriage pass.

      - rack (int) – The required racking of this instruction.

      - all_needle_rack (bool) – The all_needle racking requirement for this instruction.

    Returns:

      True if instruction was added to pass. Otherwise, False implies that the instruction cannot be added to this carriage pass.

    Return type:

      bool

  compatible_with_pass_type(instruction)

    Check if an instruction is compatible with this type of carriage pass.

    Parameters:

      instruction (Needle_Instruction) – The instruction to consider compatibility with.

    Returns:

      True if instruction is compatible with this type of carriage pass.

    Return type:

      bool

  can_add_instruction(instruction, rack, all_needle_rack)

    Check if an instruction can be added to this carriage pass.

    Parameters:

      - instruction (Needle_Instruction) – The instruction to consider adding to the carriage pass.

      - rack (int) – The required racking of this instruction.

      - all_needle_rack (bool) – The all_needle racking requirement for this instruction.

    Returns:

      True if the instruction can be added to this carriage pass. Otherwise, False.

    Return type:

      bool

  can_merge_pass(next_carriage_pass)

    Check if this carriage pass can be merged with the next one.

    Parameters:

      next_carriage_pass (Carriage_Pass) – A carriage pass that happens immediately after this carriage pass.

    Returns:

      True if these can be merged into one carriage pass.

    Return type:

      bool

  merge_carriage_pass(next_carriage_pass, check_compatibility=False)

    Merge the next carriage pass into this carriage pass.

    Parameters:

      - next_carriage_pass (Carriage_Pass) – A carriage pass that happens immediately after this carriage pass.

      - check_compatibility (bool) – If true, checks compatibility before merging.

    Returns:

      True if the merge was successful.

    Return type:

      bool

  execute(knitting_machine)

    Execute carriage pass with an implied racking operation on the given knitting machine.

    Will default to ordering xfers in a rightward ascending direction.

    Parameters:

      knitting_machine (Knitting_Machine) – The knitting machine to execute the carriage pass on.

    Returns:

      A list of executed instructions from the carriage pass.

    Return type:

      list[Knitout_Line]

  __str__()

    Return string representation of the carriage pass.

    Returns:

      String representation showing direction, instruction types, and details.

    Return type:

      str

  __list__()

    Convert carriage pass to list of knitout lines.

    Returns:

      List of knitout lines from this carriage pass.

    Return type:

      list[Knitout_Line]

  __len__()

    Get the number of instructions in the carriage pass.

    Returns:

      Number of instructions in the carriage pass.

    Return type:

      int

  __repr__()

    Return detailed representation of the carriage pass.

    Returns:

      String representation of the internal instructions list.

    Return type:

      str

  __iter__()

    Iterate over the instructions in the carriage pass.

    Returns:

      Iterator over the instructions.

    Return type:

      Iterator[Needle_Instruction]

  __getitem__(item)

    Get instruction(s) by index or slice.

    Parameters:

      item (int | slice) – Index or slice to retrieve.

    Returns:

      Instruction or list of instructions at the specified index/slice.

    Return type:

      Knitout_Line | list[Knitout_Line]

  __hash__()

    Get hash of the carriage pass based on creation time.

    Returns:

      Hash value based on creation time.

    Return type:

      int