virtual_knitting_machine.machine_components.needles.Needle module

A module containing the Needle class and related functions for virtual knitting machine operations.

This module provides the core Needle class which represents individual needles on a knitting machine. Needles can be on the front or back bed and can hold loops for knitting operations. The module includes functionality for loop management, needle positioning, and various knitting operations.

class Needle_Specification(*args, **kwargs)[source]

Bases: Protocol

Protocol for the positional details of a Needle object.

property is_front: bool: Returns: bool: True if this needle is on the front bed.

property position: int: Returns: int: The index on the machine bed of the needle.

opposite()[source]

Returns:: The needle on the opposite bed at the same position.
Return type:: Needle_Specification

property is_back: bool: Returns: bool: True if the needle is on the back bed. False, otherwise.

property is_slider: bool: Returns: bool: True if the needle is a slider, False otherwise.

property pull_direction: Pull_Direction

Get the direction this needle pulls loops during knit operations.

Returns:: BtF (Back to Front) for front needles, FtB (Front to Back) for back needles.
Return type:: Pull_Direction

slot_by_racking(racking)[source]

The slot number indicates the front-bed alignment of the given needle. For front bed needles this is equivalent to the position. For back bed needles this is dependent on the racking alignment of the beds.

Parameters:: racking (int) – The racking alignment to determine the slot number from.
Returns:: The slot number of the given component for the given racking.
Return type:: int

Notes

Racking Calculations: * R = F - B * F = R + B * B = F - R.

offset(offset)[source]

Get a needle offset by the specified amount on the same bed.

Parameters:: offset (int) – The amount to offset the needle position.
Returns:: The needle offset spaces away on the same bed.
Return type:: Needle

__str__()[source]

Return string representation of the needle.

Returns:: String representation (e.g., ‘f5’ for front needle at position 5, ‘bs2’ for back slider at position 2).
Return type:: str

__repr__()[source]

Return string representation of the needle.

Returns:: String representation of the needle.
Return type:: str

__hash__()[source]

Return hash value for the needle.

Returns:: Hash value based on position, bed side, and slider state.
Return type:: int

__lt__(other)[source]

Compare if this needle is less than another needle or number.

Parameters:: other (Needle | int | float) – The other needle or number to compare with.
Returns:: True if this needle’s position is less than the other value. If the needles are at the same location but in opposite positions (back vs. front), the front needle is considered less than the back. This orders needles as front-to-back in a leftward carriage pass.
Return type:: bool

__eq__(other)[source]

Check equality with another needle.

Parameters:: other (Needle) – The other needle to compare with.
Returns:: True if needles are equal (same bed, position, and slider status).
Return type:: bool

__int__()[source]

Returns:: The needle position.
Return type:: int

__add__(other)[source]

Add another needle’s position or an integer to this needle’s position.

Parameters:: other (Needle_Specification | int) – The needle or integer to add.
Returns:: New needle with the sum position on the same bed.
Return type:: Needle

__radd__(other)[source]

Right-hand add operation.

Parameters:: other (int) – The integer to add.
Returns:: New needle with the sum position on the same bed.
Return type:: Needle

__sub__(other)[source]

Subtract another needle’s position or an integer from this needle’s position.

Parameters:: other (Needle | int) – The needle or integer to subtract.
Returns:: New needle with the difference position on the same bed.
Return type:: Needle

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__init__(*args, **kwargs)

class Needle_Position(is_front, position, is_slider)[source]

Bases: Needle_Specification

__init__(is_front, position, is_slider)[source]

property is_front: bool: Returns: bool: True if this needle is on the front bed.

property position: int: Returns: int: The index on the machine bed of the needle.

property is_slider: bool: Returns: bool: True if the needle is a slider, False otherwise.

opposite()[source]

Returns:: The needle on the opposite bed at the same position.
Return type:: Needle_Specification

offset(offset)[source]

Get a needle offset by the specified amount on the same bed.

Parameters:: offset (int) – The amount to offset the needle position.
Returns:: The needle offset spaces away on the same bed.
Return type:: Needle

__add__(other)

Add another needle’s position or an integer to this needle’s position.

Parameters:: other (Needle_Specification | int) – The needle or integer to add.
Returns:: New needle with the sum position on the same bed.
Return type:: Needle

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__eq__(other)

Check equality with another needle.

Parameters:: other (Needle) – The other needle to compare with.
Returns:: True if needles are equal (same bed, position, and slider status).
Return type:: bool

__hash__()

Return hash value for the needle.

Returns:: Hash value based on position, bed side, and slider state.
Return type:: int

__int__()

Returns:: The needle position.
Return type:: int

__lt__(other)

Compare if this needle is less than another needle or number.

Parameters:: other (Needle | int | float) – The other needle or number to compare with.
Returns:: True if this needle’s position is less than the other value. If the needles are at the same location but in opposite positions (back vs. front), the front needle is considered less than the back. This orders needles as front-to-back in a leftward carriage pass.
Return type:: bool

__radd__(other)

Right-hand add operation.

Parameters:: other (int) – The integer to add.
Returns:: New needle with the sum position on the same bed.
Return type:: Needle

__repr__()

Return string representation of the needle.

Returns:: String representation of the needle.
Return type:: str

__str__()

Return string representation of the needle.

Returns:: String representation (e.g., ‘f5’ for front needle at position 5, ‘bs2’ for back slider at position 2).
Return type:: str

__sub__(other)

Subtract another needle’s position or an integer from this needle’s position.

Parameters:: other (Needle | int) – The needle or integer to subtract.
Returns:: New needle with the difference position on the same bed.
Return type:: Needle

property is_back: bool: Returns: bool: True if the needle is on the back bed. False, otherwise.

property pull_direction: Pull_Direction

Get the direction this needle pulls loops during knit operations.

Returns:: BtF (Back to Front) for front needles, FtB (Front to Back) for back needles.
Return type:: Pull_Direction

slot_by_racking(racking)

The slot number indicates the front-bed alignment of the given needle. For front bed needles this is equivalent to the position. For back bed needles this is dependent on the racking alignment of the beds.

Parameters:: racking (int) – The racking alignment to determine the slot number from.
Returns:: The slot number of the given component for the given racking.
Return type:: int

Notes

Racking Calculations: * R = F - B * F = R + B * B = F - R.

class Needle(is_front, position, knitting_machine)[source]

Bases: Needle_Specification, Slotted_Position[Machine_LoopT]

A class for managing individual needles on a knitting machine.

This class represents a needle on either the front or back bed of a knitting machine. Each needle can hold multiple loops and provides methods for knitting operations, loop transfers, and position calculations.

held_loops

List of loops currently held by this needle.

Type:: list[Machine_Knit_Loop]

__init__(is_front, position, knitting_machine)[source]

Initialize a new needle.

Parameters:

is_front (bool) – True if this is a front bed needle, False for back bed.
position (int) – The needle index/position on the machine bed.
knitting_machine (Knitting_Machine_State) – The machine that owns this needle.

property gauged_layers: int: Returns: int: The gauge (number of layers) currently knitting in.

property sheet: int: Returns: int: The position of the sheet in the gauge.

property position_in_sheet: int: Returns: int: The position of this needle in the sheet in the current gauged-schema.

property knitting_machine: Knitting_Machine_State[Machine_LoopT, Any]: Returns: Knitting_Machine_State: The knitting machine that owns this component.

property gauge_neighbors: list[Self]: Returns: list[Sheet_Needle]: List of needles that neighbor this loop in sheets at the current gauge layering.

property is_front: bool: Returns: bool: True if this needle is on the front bed.

property position: int: Returns: int: The index on the machine bed of the needle.

property slot_number: int

The slot number indicates the front-bed alignment of the given needle. For front bed needles this is equivalent to the position. For back bed needles this is dependent on the racking alignment of the beds.

Returns:: The slot number of the given component for the given racking.
Return type:: int

Notes

Racking Calculations: * R = F - B * F = R + B * B = F - R.

property has_loops: bool

Check if the needle is currently holding any loops.

Returns:: True if needle is holding loops, False otherwise.
Return type:: bool

property needle_position: Needle_Position: Returns: Needle_Position: The Needle_Position of this needle, not associated with the knitting machine.

opposite()[source]

Returns:: The needle on the opposite bed at the same position.
Return type:: Needle

offset(offset)[source]

Get a needle offset by the specified amount on the same bed.

Parameters:: offset (int) – The amount to offset the needle position.
Returns:: The needle offset spaces away on the same bed.
Return type:: Needle

main_needle()[source]

Get the non-slider needle at this needle position.

Returns:: The non-slider needle at this needle position.
Return type:: Needle

active_floats()[source]

Get active floats connecting to loops on this needle.

Returns:: Dictionary of loops that are active keyed to active yarn-wise neighbors. Each key-value pair represents a directed float where key comes before value on the yarns in the system.
Return type:: dict[Machine_Knit_Loop, Machine_Knit_Loop]

float_overlaps_needle(u, v)[source]

Check if a float between two loops overlaps this needle’s position.

Parameters:

u (Machine_Knit_Loop) – Machine_Knit_Loop at start of float.
v (Machine_Knit_Loop) – Machine_Knit_Loop at end of float.

Returns:

True if the float between u and v overlaps the position of this needle.

Return type:

bool

add_loop(loop)[source]

Add a loop to the set of currently held loops.

Parameters:: loop (Machine_Knit_Loop) – Loop to add onto needle.

add_loops(loops)[source]

Add multiple loops to the held set.

Parameters:: loops (Sequence[Machine_Knit_Loop]) – List of loops to place onto needle.

transfer_loops(target_needle)[source]

Transfer all loops from this needle to a target needle.

Parameters:: target_needle (Needle) – Needle to transfer loops to.
Returns:: Loops that were transferred.
Return type:: list[Machine_Knit_Loop]

drop()[source]

Drop all held loops by releasing them from the needle.

Returns:: The loops that were dropped.
Return type:: list[Machine_Knit_Loop]

static needle_position_from_sheet_and_gauge(sheet_pos, sheet, gauge)[source]

Parameters:

sheet_pos (int) – The position in the sheet.
sheet (int) – The sheet being used.
gauge (int) – The number of sheets supported by the gauge.

Returns:

The position of the needle on the bed based on the given information about its position in a sheet.

Return type:

int

static iterates_over_needles(needles)[source]

Parameters:: needles (Iterable[Needle_Specification]) – The needles to iterate over and determine that they are all Needles.
Returns:: Returns true if all elements in needles are needle objects. Typing system will recognize this guarantee.
Return type:: bool, TypeGuard[Needle]

__rsub__(other)[source]

Right-hand subtract operation.

Parameters:: other (int) – The integer to subtract from.
Returns:: New needle with the difference position on the same bed.
Return type:: Needle

__add__(other)

Add another needle’s position or an integer to this needle’s position.

Parameters:: other (Needle_Specification | int) – The needle or integer to add.
Returns:: New needle with the sum position on the same bed.
Return type:: Needle

classmethod __class_getitem__(params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ….

__eq__(other)

Check equality with another needle.

Parameters:: other (Needle) – The other needle to compare with.
Returns:: True if needles are equal (same bed, position, and slider status).
Return type:: bool

__hash__()

Return hash value for the needle.

Returns:: Hash value based on position, bed side, and slider state.
Return type:: int

__int__()

Returns:: The needle position.
Return type:: int

__lt__(other)

Compare if this needle is less than another needle or number.

Parameters:: other (Needle | int | float) – The other needle or number to compare with.
Returns:: True if this needle’s position is less than the other value. If the needles are at the same location but in opposite positions (back vs. front), the front needle is considered less than the back. This orders needles as front-to-back in a leftward carriage pass.
Return type:: bool

__radd__(other)

Right-hand add operation.

Parameters:: other (int) – The integer to add.
Returns:: New needle with the sum position on the same bed.
Return type:: Needle

__repr__()

Return string representation of the needle.

Returns:: String representation of the needle.
Return type:: str

__str__()

Return string representation of the needle.

Returns:: String representation (e.g., ‘f5’ for front needle at position 5, ‘bs2’ for back slider at position 2).
Return type:: str

__sub__(other)

Subtract another needle’s position or an integer from this needle’s position.

Parameters:: other (Needle | int) – The needle or integer to subtract.
Returns:: New needle with the difference position on the same bed.
Return type:: Needle

aligned_with_slot(slot)

Parameters:: slot (int | Slotted_Position) – The slot to compare to.
Returns:: True if this is positioned at the same slot, False otherwise.
Return type:: bool

direction_to_slot(slot)

Parameters:: slot (int) – The slot to find a direction towards.
Returns:: The direction of carriage movement from this component to the slot or None if the slots are aligned.
Return type:: Carriage_Pass_Direction | None

handle_violations(response_policy=None, handler=None)

Context manager that catches exceptions and routes them through the violation policy.

Parameters:

response_policy (ViolationResponse | Violation, optional) – The ViolationResponse policy for this code block. If given a Violation, the response will be the policy assigned to that violation in the violation policy. Defaults to the response will be the default response of the violation policy.
handler (Callable[..., Any], optional) – Optional handler to attempt before falling back to the policy response.

in_pass_direction(slot, direction)

Parameters:

slot (int | Slotted_Position) – The slot following this slot in a carriage pass movement.
direction (Carriage_Pass_Direction) – The direction to test.

Returns:

True if the given slot is after this slot in the given direction. False otherwise.

Return type:

bool

property is_back: bool: Returns: bool: True if the needle is on the back bed. False, otherwise.

property is_slider: bool: Returns: bool: True if the needle is a slider, False otherwise.

left_of_slot(slot)

Parameters:: slot (int | Slotted_Position) – The slot to compare to.
Returns:: True if this is positioned left of the given slot, False otherwise.
Return type:: bool

property machine_is_all_needle_racked: bool: Returns: bool: True if the knitting machine is racked for all needle knitting.

property machine_racking: int: Returns: int: The racking of the knitting machine.

property machine_specification: Knitting_Machine_Specification[Machine_LoopT]: Returns: Knitting_Machine_Specification[Machine_LoopT]: The machine specification of the machine associated with this component.

property needle_count_of_machine: int: Returns: int: The number of needles on each bed of the knitting machine. Defaults to the bed size in the knitting machine specification.

property pull_direction: Pull_Direction

Get the direction this needle pulls loops during knit operations.

Returns:: BtF (Back to Front) for front needles, FtB (Front to Back) for back needles.
Return type:: Pull_Direction

right_of_slot(slot)

Parameters:: slot (int | Slotted_Position) – The slot to compare to.
Returns:: True if this is positioned right of the given slot, False otherwise.
Return type:: bool

property rightmost_slot_on_machine: int: Returns: int: The rightmost slot on this knitting machine. Defaults to the standard bed size in the knitting machine specification.

set_response_for(violation, response=None)

Sets the response for the given violation to the given response.

Parameters:

violation (Violation) – The violation to set the response for.
response (ViolationResponse, optional) – The response to set for the given violation. Defaults to the default response of this policy.

slot_by_racking(racking)

The slot number indicates the front-bed alignment of the given needle. For front bed needles this is equivalent to the position. For back bed needles this is dependent on the racking alignment of the beds.

Parameters:: racking (int) – The racking alignment to determine the slot number from.
Returns:: The slot number of the given component for the given racking.
Return type:: int

Notes

Racking Calculations: * R = F - B * F = R + B * B = F - R.

property violation_policy: Knitting_Machine_Error_Policy: Returns: Knitting_Machine_Error_Policy: The policy for handling machine state errors.