Element Reference Counter

Reuse elements from the same index of the same register

If one element in one register is read more than once, playing the animation only once is much better to avoid overlapping element units on the scene.

When reading one element from one register, the accessed element is recorded. If the element is reaccessed, the recorded element is used rather than creating a new element.

The recorded element is identified by all the following attributes:

The source register.
The element index to access the register.
The register index to access the register.
The bit offset of LSB.
The width of the accessed element.

When reading one element from one register, return the recorded element only when all the above attributes match.

isa_manim.isa_scene.isa_elem_refcount.IsaElemRefCount.set_elem_source records one element and the source attributes of this element. isa_manim.isa_scene.isa_elem_refcount.IsaElemRefCount.get_elem_by_source returns the record element by the source attributes. If no matched recorded element, get_elem_by_source returns None.

Duplicate elements with multiple consumers

If one element is used as source operands of more than one animation, this element should be duplicated.

The animation to create one element is referenced as the producer. The animation referencing one element as a source is referenced as the consumer. In most situations, one element has only one producer and multiple consumers.

isa_manim.isa_scene.isa_elem_refcount.IsaElemRefCount.set_elem_producer registers one element when the element is generated. The initial value of the reference counter is 0. set_elem_producer is applied where the element unit is created.
isa_manim.isa_scene.isa_elem_refcount.IsaElemRefCount.set_elem_cusumer registers the last consumer animation and increases the reference counter by 1. The set_elem_cusumer is applied where the element unit is used as the source.
If the reference counter is 0, isa_manim.isa_scene.isa_elem_refcount.IsaElemRefCount.get_duplicate_item returns the original element. If the reference counter is higher than 1, get_duplicate_item returns a copy of the element unit. Meanwhile, the reference counter decreases by 1.

For example, one element A from vector Zm operates with all elements in Zn in one vector instruction. The 0-th element of Zn operates with the original element A. Other elements of Zn operate with a copy of A. The copied elements will be added to the scene before the last consumer animation.

flowchart TB

A1((Read one element<br/>from the register))

subgraph Copy element
A2[Element unit A]
A31[Element unit A']
A32[Element unit A'']
A33[Element unit A''']
end

A1-->A2
A2--copy-->A31--copy-->A32--copy-->A33

subgraph Add element to scene
A41[Add A']
A42[Add A'']
A43[Add A''']
A44((*))
end

A2-->A41
A31-->A42
A32-->A43
A33-->A44

subgraph Operate animation
A41-->operate0
A42-->operate1
A43-->operate2
A44-->operate3
end

operate0-->End[More animations]
operate1-->End
operate2-->End
operate3-->End

General flow within animation API

The general flow within an animation API is shown below:

flowchart TB

A1[Call <code>get_duplicate_item</code> for source elements]
A2[Create destination elements]
A3[Play animations<br>Animations operate on duplicated element]
A4[Call <code>set_elem_cusumer</code> for source elements]
A5[Call <code>set_elem_producer</code> for destination elements]

A1-->A2-->A3-->A4-->A5

_IsaElemSourceItem

Data structure to record the source of one element.

Attributes:

Name	Type	Description
`register`	`RegUnit`	Register where the element comes from.
`index`	`int`	Element index to access the register.
`reg_idx`	`int`	Register index to access the register.
`offset`	`int`	Offset of LSB.

`init(register, index, reg_idx, offset)`

Construct the data structure.

Parameters:

Name	Type	Description	Default
`register`	`RegUnit`	Register where the element comes from.	required
`index`	`int`	Element index to access the register.	required
`reg_idx`	`int`	Register index to access the register.	required
`offset`	`int`	Offset of LSB.	required

`is_match(register, index, reg_idx, offset)`

Check whether the specified arguments match this data structure.

Parameters:

Name	Type	Description	Default
`register`	`RegUnit`	Register where the element comes from.	required
`index`	`int`	Element index to access the register.	required
`reg_idx`	`int`	Register index to access the register.	required
`offset`	`int`	Offset of LSB.	required

Returns:

Type	Description
`bool`	If arguments match, return True.

_IsaElemRefCountItem

Data structure of reference counter.

Attributes:

Name	Type	Description
`refer_count`	`int`	Reference counter. 0 means there is no reference of this unit.
`last_consumer`	`IsaAnimateItem`	Animation to consumer this element unit.
`last_dep`	`Mobject`	Dependency unit of last animation.

`init()`

Constructor data structure of reference counter.

Reset member variables.

`get_dup_elem(elem)`

Get a copy of element if the element has been referenced.

If the element has not been referenced, return the element unit itself. Otherwise, return a copy of the element.

Add duplicated element after the last consumer animation.

Parameters:

Name	Type	Description	Default
`elem`	`ElemUnit`	Element unit.	required

Returns:

Type	Description
`ElemUnit`	Return a copy of the specified element unit.

`set_cusumer(consumer, dep)`

Set the consumer of element. Increase the reference counter.

Parameters:

Name	Type	Description	Default
`consumer`	`IsaAnimateItem`	The animation consumes this animation.	required
`dep`	`Mobject`	Dependency unit.	required

`set_producer(dep)`

Set the producer of element.

Parameters:

Name	Type	Description	Default
`dep`	`Mobject`	Dependency unit.	required

IsaElemRefCount

Data structure for element reference counter.

`init()`

Construct data structure for element reference counter.

Attributes:

Name	Type	Description
`elem_source_dict`		Dictionary of element source. Key is element unit, and value is the source register and the index to access the register.
`elem_refcount_dict`		Dictionary of reference counter. Key is element unit, and value contains the reference counter and the last consumer and dependency.

`get_duplicate_item(elem)`

Get a copy of element if the element has been referenced.

Parameters:

Name	Type	Description	Default
`elem`	`ElemUnit`	Element unit.	required

Returns:

Type	Description
`ElemUnit`	Return a copy of the specified element unit.

`get_elem_by_source(register, width, reg_idx, index, offset)`

Get one element unit by source.

Parameters:

Name	Type	Description	Default
`register`	`RegUnit`	The source register.	required
`width`	`int`	Width of element.	required
`reg_idx`	`int`	Register index to access the register.	required
`index`	`int`	Element index to access the reigster.	required
`offset`	`int`	LSB offset.	required

Returns:

Type	Description
`ElemUnit`	Return the element unit specified by the source register and index. Otherwise, return None.

`get_last_deps(*elem_list)`

Return the depedency units (Registers, Memory and Functions) of specified list.

If elem_list contains only one element unit, return a single unit.
- Return None if no dependency unit is found.
Otherwise, return a list of units.
- Return an empty list if no dependency unit is found.

Returns:

Type	Description
`Union[List[Mobject], Mobject, None]`	Return a list of dependency units or a single dependency unit.

`set_elem_cusumer(elem, consumer, dep)`

Set the consumer of one element unit. Called when one animation consumes the element unit.

Parameters:

Name	Type	Description	Default
`elem`	`ElemUnit`	Element unit.	required
`consumer`	`IsaAnimateItem`	Last consumer animation of this element unit.	required
`dep`	`Mobject`	Last dependency unit, RegUnit, FunctionUnit or MemoryUnit.	required

`set_elem_producer(elem, dep)`

Set the producer of one element unit. Called when one animation produces the element unit.

Parameters:

Name	Type	Description	Default
`elem`	`ElemUnit`	Element unit.	required
`dep`	`Mobject`	Last dependency unit, RegUnit, FunctionUnit or MemoryUnit.	required

`set_elem_source(elem, register, reg_idx, index, offset)`

Set the source of one element unit.

Parameters:

Name	Type	Description	Default
`elem`	`ElemUnit`	Element unit.	required
`register`	`RegUnit`	The source register.	required
`reg_idx`	`int`	Register index to access the register.	required
`index`	`int`	Element index to access the reigster.	required
`offset`	`int`	LSB offset.	required

Element Reference Counter

Reuse elements from the same index of the same register

Duplicate elements with multiple consumers

General flow within animation API

_IsaElemSourceItem

__init__(register, index, reg_idx, offset)

is_match(register, index, reg_idx, offset)

_IsaElemRefCountItem

__init__()

get_dup_elem(elem)

set_cusumer(consumer, dep)

set_producer(dep)

IsaElemRefCount

__init__()

get_duplicate_item(elem)

get_elem_by_source(register, width, reg_idx, index, offset)

get_last_deps(*elem_list)

set_elem_cusumer(elem, consumer, dep)

set_elem_producer(elem, dep)

set_elem_source(elem, register, reg_idx, index, offset)

`init(register, index, reg_idx, offset)`

`is_match(register, index, reg_idx, offset)`

`init()`

`get_dup_elem(elem)`

`set_cusumer(consumer, dep)`

`set_producer(dep)`

`init()`

`get_duplicate_item(elem)`

`get_elem_by_source(register, width, reg_idx, index, offset)`

`get_last_deps(*elem_list)`

`set_elem_cusumer(elem, consumer, dep)`

`set_elem_producer(elem, dep)`

`set_elem_source(elem, register, reg_idx, index, offset)`