Gas Integrator dynamics node

A microsolver that applies forces to a particle fluid system.

On this page

Parameters
Inputs
Outputs
Locals

The Gas Integrator DOP is a microsolver used to build larger fluid simulations. It applies forces to particles in a particle fluid system and adjusts the velocities and positions of the particles according to the applied forces. It is currently used to apply in the Particle Fluid Solver DOP.

Parameters ¶

Geometry

The geometry containing the points to integrate forces and velocities for.

Point Group

An optional point group to specify which points will be integrated.

Simulation Method

The numerical simulation method to be used when applying forces to the particle system.

Euler

This is a basic first-order simulation method.

It is the fastest available method, but due to its simplicity, may require very small substeps to ensure stability.

Midpoint

This is a second-order simulation method that is slower but more stable than the first-order Euler method.

Runge-Kutta

This is the standard fourth-order Runge-Kutta simulation method. Again, it is slower than both the Euler and Midpoint methods, but also more stable.

Runge-Kutta-Fehlberg

This method combines fourth and fifth-order simulation methods to adaptively determine an appropriate substep length for the simulation by comparing the results of these methods.

Note

This method must be used in conjunction with the Gas Substep node.

Runge-Kutta 2(1)

Like the Runge-Kutta-Fehlberg (RKF) method, this method also combines two different simulation steps to adaptively determine an appropriate substep length.

It combines first and second-order methods. Like the RKF method, this method must be used in conjunction with the Gas Substep node.

Note

This method must be used in conjunction with the Gas Substep node.

Runge-Kutta 3(2)

Like the Runge-Kutta-Fehlberg (RKF) method, this method also combines two different simulation steps to adaptively determine an appropriate substep length.

It combines second and third-order methods. Like the RKF method, this method must be used in conjunction with the Gas Substep node.

Note

This method must be used in conjunction with the Gas Substep node.

Advection Method

The technique used to update particle positions.

Standard

Particle positions are updated directly using the current particle velocity and time step length.

XSPH

Particle positions are updated using a velocity which is blended between each particle’s current velocity and the average velocity of its neighbors.

XSPH Constant

When Advection Method is set to “XSPH”, this constant controls the degree of blending between a particle’s velocity and the velocity of its neighbors. A value of zero ignores neighbor velocities entirely, while larger values increasingly make use of neighbor velocities.

Error Tolerance

This parameter applies exclusively to the Runge-Kutta-Fehlberg, Runge-Kutta 2(1) and Runge-Kutta 3(2) methods.

It controls the amount of error tolerated by these methods when setting a new substep length for the simulation. A higher error tolerance results in less substepping, but may lead to more instability in the system.

Substep Repetition Tolerance

This parameter applies exclusively to the Runge-Kutta-Fehlberg, Runge-Kutta 2(1) and Runge-Kutta 3(2) methods. After each application of the Gas Integrator DOP, these methods recommend a new substep length for the input system.

If the recommended substep is lower than the previous substep, that substep may need to be repeated. This parameter controls how willing the Gas Integrator is to repeat a substep.

For example, if the Substep Repetition Tolerance has a value of 0.75, then substeps will only be repeated if the new recommended substep is less than 0.75 times the length of the preceding substep.

Minimum Substep

This parameter applies exclusively to the Runge-Kutta-Fehlberg, Runge-Kutta 2(1) and Runge-Kutta 3(2) methods.

It controls the minimum substep length that any of these methods will recommend.

Maximum Substep

This parameter applies exclusively to the Runge-Kutta-Fehlberg, Runge-Kutta 2(1) and Runge-Kutta 3(2) methods.

It controls the maximum substep length that any of these methods will recommend.

Scale Forces By

The quantity by which forces should be scaled to determine the acceleration of particles in the system. Density is typically used to scale forces in a particle fluid simulation.

Enable Collision Detection

Enables collision detection/response between particles in the system and rigid body objects.

Move Out of SDF Colliders

When colliding with SDFs, do not do bouncing but instead just move particles out of them. This is can be more robust when SDF colliders overlap.

Store Original Point Positions

Some types of collision detection will create a previous attribute to store the previous frame’s particle position. Turning this on will always store this data. It will also store it prior to the position integration of this node (rather than after collision detection) making for a more useful value for introspection later in the simulation.

Store Final Point Positions

If Store Original Point Positions is not set, and the pprevious and has_pprevious attributes exist, they will be setup if this option is provided.

Note

All points are affected, not just those in the integration group.

Add Impact Data

Enables the addition of Impact data onto the particles. Normally these are not added to save memory, and particle collision attributes are more easily created with the Gas Collision Detect DOP.

Enable Collision Feedback

Enables the addition of Feedback impacts onto colliding objects, which are required for two-way interaction.

Compute UVs for Collisions

Determine if the otherprimnum and otherprim[u/v] components of the collision impact should be computed. Disabling the computation avoids sending additional rays for collision events, speeding up the simulation.

Apply Forces Incrementally

When this parameter is enabled, the forces applied by each solver input are applied one at a time. When it is disabled, a single force is accumulated from all of the input solvers and then applied in a single iteration.

Integrate Velocity

When turned on, velocity is not updated from the force attribute and the force attribute is not cleared. Further, none of the sub solvers attached to the integrate will be evaluated.

This toggle only has an effect in Euler update mode.

Integrate Orientation

When this toggle is disabled, the integrator only affects the position and velocity attributes of particles in response to values set in the force attribute by the node’s input solvers.

When this toggle is enabled, the integrator also affects the orientation and angular velocity attributes of particles in response to values set in the torque attribute by the node’s input solvers.

Default Particle Size

To allow robust collision detection the particles are treated as finite-sized spheres. By default pscale is used, but if the pscale attribute is missing then this size is used.

SDF collisions will use 0 for pscale if it is missing as they can unambiguously determine which side they are on.

Use PScale for SDF

Uses the pscale attribute to collide with SDF collision objects. For backwards compatibility, the default is to ignore pscale with these collisions.

PScale Is Radius

For non-SDF collisions, controls if the pscale attribute is treated as radius or a diameter.

Parameter Operations

Each data option parameter has an associated menu which specifies how that parameter operates.

Use Default

Use the value from the Default Operation menu.

Set Initial

Set the value of this parameter only when this data is created. On all subsequent timesteps, the value of this parameter is not altered. This is useful for setting up initial conditions like position and velocity.

Set Always

Always set the value of this parameter. This is useful when specific keyframed values are required over time. This could be used to keyframe the position of an object over time, or to cause the geometry from a SOP to be refetched at each timestep if the geometry is deforming.

You can also use this setting in conjunction with the local variables for a parameter value to modify a value over time. For example, in the X Position, an expression like $tx + 0.1 would cause the object to move 0.1 units to the right on each timestep.

Set Never

Do not ever set the value of this parameter. This option is most useful when using this node to modify an existing piece of data connected through the first input.

For example, an RBD State DOP may want to animate just the mass of an object, and nothing else. The Set Never option could be used on all parameters except for Mass, which would use Set Always.

Default Operation

For any parameters with their Operation menu set to Use Default, this parameter controls what operation is used.

This parameter has the same menu options and meanings as the Parameter Operations menus, but without the Use Default choice.

Make Objects Mutual Affectors

All objects connected to the first input of this node become mutual affectors.

This is equivalent to using an Affector DOP to create an affector relationship between * and * before connecting it to this node. This option makes it convenient to have all objects feeding into a solver node affect each other.

Group

When an object connector is attached to the first input of this node, this parameter can be used to choose a subset of those objects to be affected by this node.

Data Name

Indicates the name that should be used to attach the data to an object or other piece of data. If the Data Name contains a “/” (or several), that indicates traversing inside subdata.

For example, if the Fan Force DOP has the default Data Name “Forces/Fan”. This attaches the data with the name “Fan” to an existing piece of data named “Forces”. If no data named “Forces” exists, a simple piece of container data is created to hold the “Fan” subdata.

Different pieces of data have different requirements on what names should be used for them. Except in very rare situations, the default value should be used. Some exceptions are described with particular pieces of data or with solvers that make use of some particular type of data.

Unique Data Name

Turning on this parameter modifies the Data Name parameter value to ensure that the data created by this node is attached with a unique name so it will not overwrite any existing data.

With this parameter turned off, attaching two pieces of data with the same name will cause the second one to replace the first. There are situations where each type of behavior is desirable.

If an object needs to have several Fan Forces blowing on it, it is much easier to use the Unique Data Name feature to ensure that each fan does not overwrite a previous fan rather than trying to change the Data Name of each fan individually to avoid conflicts.

On the other hand, if an object is known to have RBD State data already attached to it, leaving this option turned off will allow some new RBD State data to overwrite the existing data.

Solver Per Object

The default behavior for solvers is to attach the exact same solver to all of the objects specified in the group. This allows the objects to be processed in a single pass by the solver, since the parameters are identical for each object.

However, some objects operate more logically on a single object at a time. In these cases, one may want to use $OBJID expressions to vary the solver parameters across the objects. Setting this toggle will create a separate solver per object, allowing $OBJID to vary as expected.

Setting this is also required if stamping the parameters with a Copy Data DOP.

Inputs ¶

All Inputs

Any microsolvers wired into these inputs will be executed prior to this node executing. The chain of nodes will thus be processed in a top-down manner.

Outputs ¶

First Output

The operation of this output depends on what inputs are connected to this node. If an object stream is input to this node, the output is also an object stream containing the same objects as the input (but with the data from this node attached).

If no object stream is connected to this node, the output is a data output. This data output can be connected to an Apply Data DOP, or connected directly to a data input of another data node, to attach the data from this node to an object or another piece of data.

Locals ¶

channelname

This DOP node defines a local variable for each channel and parameter on the Data Options page, with the same name as the channel. So for example, the node may have channels for Position (positionx, positiony, positionz) and a parameter for an object name (objectname).

Then there will also be local variables with the names positionx, positiony, positionz, and objectname. These variables will evaluate to the previous value for that parameter.

This previous value is always stored as part of the data attached to the object being processed. This is essentially a shortcut for a dopfield expression like:

dopfield($DOPNET, $OBJID, dataName, "Options", 0, channelname)

If the data does not already exist, then a value of zero or an empty string will be returned.

DATACT

This value is the simulation time (see variable ST) at which the current data was created. This value may not be the same as the current simulation time if this node is modifying existing data, rather than creating new data.

DATACF

This value is the simulation frame (see variable SF) at which the current data was created. This value may not be the same as the current simulation frame if this node is modifying existing data, rather than creating new data.

RELNAME