On this page | |
Since | 17.5 |
Partitions work items based on their frame and the selected frame rounding mode.
You can use this node to combine multiple subframes into a single frame unit, or to separate frames from different wedge variations. This allows you to run a simulation with integer frames that is internally loading source geometry at subframes.
For example, you can use this node to help with the following:
-
You have a simulation where the initial sim source is written out in half (0.5) frame steps, but its actual sim is output in single (1.0) frame steps.
-
You have four wedge variations and for each variation you run two simulations of 20 frames each. This gives you 1 frame per sim for each wedge, which is eight frame 1s, eight frame 2s, and so on. To render this sim, you need both sim outputs (per frame, per wedge), but you don’t want all the frame 1s from all four wedges in the same partition. You want one partition per frame for each wedge.
Tip
-
The
$HH/help/files/pdg_examples/top_partitioners
example shows how you can use common partitioner like targeted partitioning, controls for merging attributes, and splitting by attribute. -
The
$HH/help/files/pdg_examples/top_multishot
and$HH/help/files/pdg_examples/top_rop
examples show how you can use this node to group multiple simulation or render work items by their frame value.
Parameters ¶
Frame ¶
Create Partitions For
Determines which frames the partitions are created for.
Individual Frames
Create partitions for individual frames.
Distinct Frame Ranges
Frame Sequences
Frame Rounding
When partitioning work items with fractional frames, determines how the frame is converted to an integer for partitioning.
This parameter is only available when Create Partitions For is set to Individual Frames.
Round Down
Rounds the frame value down to the nearest integer. For example, values from 1.0 to 1.9 are treated as frame 1.
Round Up
Rounds the frame value up to the nearest integer. For example, values from 1.1 to 2.0 are treated as frame 2.
Round Nearest
Rounds the frame value to the nearest frame. For example, values from 1.0 to 1.49 are treated as frame 1.0, and values from 1.5 to 2.0 are treated as frame 2.
Missing Frame
Determines how the node should handle work items without a frame value.
Report Error
The node will report an error if any of the input work items are missing a frame.
Ignore Work Item
Work items without a frame will be ignored and won’t be added to any partitions.
Add Work Item to All Partitions
Use Frame for Partition Index
When on, the partitions that are created have their indexes set to the frame number assigned to the partition. When off, the partitions have their indexes set from 0 up to the number of partitions created.
When Wedge Attribute is also on, and you want to split frames by wedge index, it isn’t always possible to set the partition index to the frame number. That is because there may be different wedge variations with the same frame number. In this case, the node maintains a unique index for each partition, but the indexing begins at the first frame in the first wedge instead of at 0.
Missing Range Attribute
Determines how the node deals with work items that are missing the range attribute.
This parameter is only available when Create Partitions For is set to Frame Ranges.
Report Error
If an input work item is missing the range attribute, the node will fail to partition and report a cook error.
Report Warning
Work items that are missing the range attribute will be reported as a warning.
Ignore Work Item
Work Items that are missing the range attribute will be silently ignored.
Add To All Partitions
All work items that are missing the range attribute will be added to every partition created by the node.
Add To Last Partition
A special partition is included at the end of the list which contains all work items that are missing the range attribute.
Add to Unique Partition
A unique partition is created for each input work item that is missing the range attribute.
Range Attribute Name
Determines the name of the attribute that has the work item’s frame range start/end/step value. The attribute must have at least 2 components and be numeric.
This parameter is only available when Create Partitions For is set to Frame Ranges.
Isolate Static Frames
When on, work items that represent a single frame are put into individual partitions. The node detects static frames by checking if the start and end value in the frame range are the same.
This parameter is only available when Create Partitions For is set to Frame Ranges.
Split by Attribute
When on, work items are split into separate groups before the items are partitioned. This parameter specifies the name of the attribute on the input work items that is used to determine those groups.
For example, you can set this parameter to wedgeindex
in order to keep wedge variations in different partitions.
The following extra steps are performed when using a split attribute
-
The node looks up the value of the split attribute for each input work item.
-
The work items are then grouped based on their split attribute value. One group is created for each unique value of the split attribute.
-
The regular partitioning process is applied to each group of work items. Work items in different groups are always be in different partitions. Groups are processed in ascending order of their split attribute value.
Missing Attribute
Determines how the node should handle an input work item that does not have the split attribute.
This parameter is only available when Split by Attribute is on.
Ignore Work Item
Input work items that are missing the split attribute are not added to any of the partitions.
Add to Partitions with Matching Frame
Input work items that are missing the split attribute are added to partitions that have the same frame as the work item.
Add to All Partitions
Input work items that are missing the split attribute are added to all partitions produced by the node.
Use Default Value
Input work items that are missing the split attribute will use the value specified in the Default Value parameter instead.
Default Value
When Missing Attribute is set to Use Default Value, this parameter specifies the value to use for the split attribute for work items that don’t have the attribute.
Allow Partial Matches
When Split by Attribute is set to a list of attribute names, this parameter determines how work items with only some of the attributes should be processed. If partial matches are enabled then work items will be included in partitions based on the attributes that do exist. Otherwise, work items with only a subset of the attributes will be excluded from the partitioning step.
Merge Attributes ¶
These parameters control how attributes from input work items are merged onto the partitions produced by the node.
Merge Output Files
Determines how output files from work items in partitions are merged onto the partitions themselves. By default, all output files from the work item are copied into the partition output file list.
None
Output files are not merged onto partitions
First File
The output file(s) from the first work item in the partition are copied onto the partition.
Last File
The output file(s) from the last work item in the partition are copied onto the partition.
Unique Files
The unique file paths from all of the work items are copied onto the partition. The order of the files may change as this operation requires sorting the file list.
All Files
The output file(s) from all work items in the partition are copied onto the partition. The order of the files dependends on the order of the work items in the partition.
Merge Operations
Defines the number of attribute merge operations to perform on the partitioner node. The operations are used to merge attributes from work items in the partition onto the partition itself. Operations are performed in descending order. Attributes are merged using the first operation with a pattern that matches the attribute.
Apply Operation
Specifies the operation to perform to merge incoming attributes onto the partition. Each operation only applies only to the subset of attributes matched using the corresponding To Attributes parameter.
The following operations are available:
Ignore
Matching attributes are ignored and will not appear on the partition.
First Value
The value of each matching attribute on the first work item in the partition is kept, and values on subsequent work items are ignored
Last Value
The value of each matching attribute on the last work item in the partition is kept.
Unique Values
The unique values for each matching attribute are merged into an array. Duplicate values are discarded.
Append to Array
The values for each matching attribute are appended to an array for that attribute. All attribute values from all work items are kept.
Minimum
The minimum value for each matching attribute is kept.
Maximum
The maximum value for each matching attribute is kept.
Sum
The sum of the values in each matching attribute is stored on the partition.
Average
The average value of each matching attribute is stored on the partition.
Mode
The most common value in each matching attribute is kept.
Median
The middle value in each matching attribute is kept.
Sorted
The values for each matching attribute are merged into a sorted array.
SortedUnique
Attribute values across all work items are merged into a sorted array, and unique values are kept.
To Attributes
Specifies which attributes the corresponding Apply Operation parameter should apply to. This field can use the Attribute Pattern Syntax to specify multiple attributes.
Preserve Arrays
When on, the merge operation preserves the original array size of the incoming attributes. The merged array size is determined by the first value found across the input work items. When off, the partitioner flattens the incoming array attributes into a single sequence of values (a single scalar value) and performs the merge operation across all values.
Advanced ¶
These are advanced parameters that give you a finer level of control over the behavior of the partitioner.
Partition When
Determines when the partitioning step is performed on the input work items.
Input Items are Generated
Upstream work items are partitioned once all of them have been generated
Input Items are Cooked
Upstream work items are partitioned once all of them are cooked. This may be required when the partitioning scheme is based on the results of the work items' execution.
This makes this partitioner behave like a Wait for All node except that it may create multiple partitions.A
Partition Target(s)
Determines which node or nodes(s) should target. Work items in the target nodes are partitioned as soon as they're generated even if the target nodes are not a direct input to this node. The descendants of the target work items are added to the partitions when they become available.
Direct Input Nodes
The partitioner uses work items from its direct input nodes. This is the default behavior
Upstream Static Nodes
The partitioner will skip over dynamic input nodes and partition work items from the nearest upstream static nodes.
Custom Target Node
The partitioner will use the node specified using the Custom Target Node parameter.
Custom Target Node
Specifies the target TOP node for the partition when Partition Targets is set to Custom Target Node. The partition scheme is applied to the work items in the target TOP node instead of this node’s input work items. The target TOP node must be in the same graph and above this node.
Ignore Failed Work Items
When this toggle is enabled, the partitioner node will skip input work items that are failed and create partitions from the subset of upstream work items that succeeded. This option is only meaningful if Partition When is set to Input Items are Cooked, or when the partitioner node is wired into a dynamic node that has upstream failures.
Sort Contents By
Determines the order that work items are sorted in when accessing the partitions on this node. This also affects the sort order of output files on the partition.
None
No sorting is applied. The work items in the partition are handled in no particular order.
Work Item Index
Work items in the partition are sorted based on their index.
Input Node Order
Work items in the partition are sorted based on the order of input nodes wired into this node. If two work items are from the same input, they are then sorted by index.
Attribute
Work items in the partition are sorted based on the attribute specified in the Sort Attribute field parameter.
Sort Direction
Determines whether the work items in this node’s partitions are sorted in ascending or descending order.
Sort Attribute
Specifies the name of the attribute to sort by.
This parameter is only available when Sort Contents By is set to Attribute.
Store Items to Attrib
When on, the list of IDs corresponding to the work items in the partition are written to the specified attribute. The work item IDs are stored as an integer array. This makes it easier to recover the list of partitioned work items downstream of the partitioner node.
Examples ¶
PartitionByFrame Example for Partition by Frame TOP node
This example demonstrates how to use the Partition by Frame TOP node to wait for work items with the same frame value.
See also |