Houdini 20.5 Nodes TOP nodes

Partition by Attribute TOP node

Partitions work items based on their attributes

On this page
Since 17.5

This node provides a variety of ways to partition work items based on their attributes.

Tip

The $HH/help/files/pdg_examples/top_partitioners example shows how you can use common partitioner features like targeted partitioning, controls for merging attributes, and splitting by attribute.

Parameters

Attributes

Partition By

Determines how to create partitions from the Attribute conditions.

Attribute Name

A partition is created for each distinct attribute name in the upstream work items. All work item that have that attribute are put into the partition.

When the Partition Attributes Independently toggle is off, a single partition is created for work items that have all of the specified attributes.

Specific Attribute Values

The same as Attribute Name, but the rather than simply having the attribute the work items in the partition must also have a specific value for the attribute. The value is specified using the Value parameter in each of the conditions.

When the Partition Attributes Independently toggle is off, a single partition is created for work items that have all of the specified attribute values.

Distinct Attribute Values

A partition is created for each distinct value of the specified attribute in the list upstream work items. For example if the distinct attribute is an integer, all the work items that have a value of 0 will be placed in the same partition, all the items with a value of 1 in a different partition, etc. The values do no need to begin with zero or be consecutive.

When the Partition Attributes Independently toggle is off, the values are placed into a tuple and a partition is created for each unique tuple.

Attribute Pattern

Similar to Attribute Name, except rather than using a multiparm the attributes are specified using an attribute pattern. One partition is created for each attribute name that matches the partition The partitions are ordered alphabetically by attribute name.

When the Partition Attributes Independently toggle is off, a single partition is created that contains all work items that have at least one attribute that matches the pattern.

Sort Direction

Only available when Partition By is set to Distinct Attribute Values,or Attribute Pattern. When partitioning by values this parameter whether partitions are indexed in ascending or descending order based on their attribute values. When partitioning by pattern it determines if the matching attribute names should from sorted from A to Z or from Z to A.

Partition Attributes Independently

Determines if the Attribute conditions should be considered individually or as a collective, single condition.

Create Partition for Unmatched Items

When this toggle is enabled an extra partition will be created that contains all work items that failed to match the other Attribute conditions.

Pattern

When Partition By is set to Attribute Pattern this parameter is used to determine which attributes should be used during the partitioning step. For example, using a pattern of * ^foo would create a partition for each attribute, except for an attribute named foo.

Attributes

The number of attribute conditions.

Name

The name of the attribute.

Type

The type of the attribute, either Float, Integer, or String.

Index

This parameter determines the attribute index that the condition should check.

Value

When partitioning by Specific Attribute Value this parameter determines the attribute value that condition should check.

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 provide finer 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.

Split by Attribute

When on, the node splits input work items by the specified attribute(s) before partitioning them. The partitioning logic is evaluated on the list of work items for each distinct attribute value. Work items with different attribute values are always put into different partitions. Multiple attribute names can be specified as a space-separated list.

Missing Attribute

Determines how the node handles work items that are missing the split attribute.

This parameter is only available when Split by Attribute is on.

Ignore Work Item

Work items that are missing the split attribute are not put into any of the partitions.

Add Work Item to All Partitions

Work items that are missing the split attribute are put into all of the partitions.

Use Default Value

Work items that are missing the split attribute will use the value set by the Default Value parameter.

Default Value

Specifies the value to use for the split attribute for work items that are missing the attribute.

This parameter is only available when Missing Attribute is set to Use Default Value.

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 added to split groups based on the attributes that do exist. Otherwise, work items with only a subset of the attributes will be excluded from the partitioning step.

Set Partition Frame To

Determines how the partitioner should set the frame value on partitions created by this node. If the partitioner already sets a custom frame value, for example like with a Python Partitioner SOP or Partition by Frame SOP, then this parameter has no effect.

None

No frame value is set on partitions.

First Work Item’s Frame

The frame value from the first work item based on the current Sort Contents By sort order is copied onto the partition.

Last Work Item’s Frame

The frame value from the last work item based on the current Sort Contents By sort order is copied onto the partition.

Largest Frame

The largest frame value from all work items in the partition is used for the partition’s frame.

Smallest Frame

The smallest frame value from all work items in the partition is used for the partition’s frame.

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

AttributeNames Example for Partition by Attribute TOP node

This example demonstrates how the Partition by Attribute TOP node can be used to group work items by the existence of attribute(s).

AttributeValue Example for Partition by Attribute TOP node

This example file demonstrates how work items can be partition by specific attribute value(s).

DistinctValues Example for Partition by Attribute TOP node

This example file demonstrates how to create a partition for each unique attribute value on the list of upstream work items.

See also

TOP nodes