# Carbon Simulation¶

## Description¶

This node defines a Carbon Simulation solver and its parameters.

The Carbon Simulation node manages and solves constraints between dynamic objects. The Carbon Simulation node also synchronizes the dynamic update of the different kinematic objects.

Attach a Carbon Collider node together with a Carbon Cloth or Carbon Rigid Body node to a merge node, then the merge node to this node, to form a simple simulation scenario.

## Inputs¶

Input #1: *objects*

Any Object Nodes, Relationship Nodes and Solver Data Nodes used in this simulation.

## Parameters¶

Gravity `gravityx`

`gravityy`

`gravityz`

Acceleration of gravity (length/time^2).

Iterations `iterations`

Number of iterations per simulation subdivision.

Iterations control the convergence, so the more iterations the better the convergence towards the problem solution. The convergence is directly impacted by the size of the problem, the mass ratios between objects interacting, the stiffness desired, etc… In other words, in a complex system it is impossible to tell how many iterations might be needed to converge at a given precision and it gets even worse considering that most problems end up over constrained locally by pinching or collisions singularities. So, we allow you to set a hard limit in number of iterations to balance processing time and convergence while avoiding systems iterating forever around a solution that might not even exist.

Subdivisions `subdivisions`

Number of subdivisions per frame (simulationTimeStep = 1 / (framesPerSecond * subdivisions)).

Imagine you have a scene at 24 frames per second. So, if you set 10 subdivisions, then the physics solver will perform 10 substeps between each frame, interpolating the information internally to run at 240 Hertz (10 x 24 per second). So, the output is still at a frame every 1/24 seconds but the solver will run 10 solves per frame through substeps of 1/240 second. The number of subdivisions is very important because it controls the accuracy of the collision. If you have small / thin objects and fast motion, then you need higher number of subdivisions to better sample the time to avoid objects interpenetrating. The number of subdivisions is also very important to capture fast oscillations. The time sampling must be smaller than the frequency of the oscillation and the number of subdivisions is your friend in this case too. In summary, any simulation error is relative to the simulation time step (time step = frame step / subdivisions). So, either reducing the frame step or increasing the number of subdivisions will increase precision.

**Iterations & Subdivisions Relationship**
The number of iterations and the number of subdivisions also combine.
For example, imagine a simulation using 10 subdivisions but also needing 50
iterations to converge as desired.
The same problem with a setting of 20 subdivisions might only need 20 iterations
or less to reach the desired convergence while increasing the accuracy of a
problem that struggled to converge.
The computation time in both cases is roughly the same since the physics will
execute 500 solver steps with 10 collision detections in the first case and 400
solver steps with 20 collision detections in the second case.

**Convergence**
The Carbon solver is an iterative solver, meaning that during each simulated
frame, it will run a fixed number of iterations towards the “correct” physical
solution.
The larger the constraints network (i.e. number of triangles/quads), the longer
it will take any iterative solver to reach a converged state.
This means that with a fixed number of iterations/subdivisions, we will almost
never reach a converged state, because most problems are too large.

Time Scale `timeScale`

Time scale ratio of the scene (1/ time). Use 1 for one second per unit, 0.001 for 1ms per unit…etc. The time scale works the same way as the length scale by applying to parameters that are time dependent such as acceleration of gravity or stiffness. The default time scale is 1. A smaller time scale will slow down every time related effects such as acceleration of gravity. A larger time scale will instead accelerate the effect of time dependent effects. The time scale does not change the time step value which means that when the time scale is animated, the momentum / velocity of objects only decreases as the object is affected by time scaled effects such as acceleration of gravity, stiffness of material, viscous damping, etc… over the course of multiple frames.

Time Warp `timeWarp`

Time warp is a multiplier of the time step and it changes the meaning of the elapsed time by contraction or dilatation. A time warp of 1 has a neutral effect. A time warp smaller or bigger than 1 means that the elapsed time during a simulation update is smaller or bigger than the frame elapsed time. This can be used to produce the illusion of slow motion, but animated objects need be have their slow motion baked in, too, in order to be synchronized with the simulation time warp. Time warp affects everything time related, while time scaling does not affect the meaning of the elapsed time.

Scale `scale`

Length scale ratio of the scene (1/length). Use 1 for one meter per unit, 0.01 for one cm per unit …etc.

Simulation scale not only affect the objects, but also the scene conditions, such as gravity. Here is a simple example: you look at a jenga pile falling: It’s fast. Now, compare this to a falling building, it looks very slow because the point of view and scale are bigger.

Now, imagine an artist created a jenga pile, but with units that made it the scale of a building. Everything would look like in low gravity, slow falling. The obvious solution would be to scale down the whole scene including the camera position etc… and then get the right perception. But this would be very time consuming. In order to avoid this, we have the Simulation Scale parameter, which invert-scales all parameters that are length dependent such as gravity and density.

Max Linear Motion `maxLinearMotion`

Maximum linear motion per simulation time step (length). The maximum linear motion is like a speed limiter. It is the maximum displacement per subdivision the Carbon simulation will allow on anything. So for example if it is set to 0.5 and the number of subdivision is 10, a Carbon rigid body maximum speed will be 5 of the scene unit per frame. Same for any of the points on a cloth … etc. It is a useful feature to avoid objects disappearing into the horizon when something blows up, or to keep high speed objects under tight control.

Damping `damping`

Damping force coefficient (1/time).

Panic Time `panicTime`

Valid simulation subdivision time threshold in seconds. If a subdivision takes longer to simulate, then the simulation is interrupted. Panic Time is accumulated in all solver stages per subdivision, allowing for early detection and interrupt. Allows to recover the session in case of heavy geometry corruption as an alternative of pressing the escape key. A value of 0 internally defaults to 3600, effectively disabling the Panic Time.

## Parameter File¶

Use Parameter File `fileOverride`

Replace parameter values by expressions fetching the values from the loaded parameter file. Parameter values from the exclusion filter are left unchanged.

File Name `fileName`

Json file path to save this node’s current parameters to, and load the parameter file from.

Save `save`

Save this node’s current parameters to the specified file.

Load `load`

Load or reload the specified parameter file. As the overriding expressions always fetch values from the last loaded parameter file, and not from the file itself, use this button to refresh the loaded current parameter file with the values on disk.

Reload Every Time The Node Is Loaded `reload`

Automatically reload the parameter file when the scene is loaded. If the specified file cannot be found then the overriding expressions will use the values of the last loaded parameter file instead.

Exclusion Filter `exclusionFilter`

The exclusion filter allows to select which of the parameters are not to be replaced by the overriding expressions, therefore keeping their original values while all other parameters will evaluate with the values set from the last loaded parameter file.

## Debug Output¶

Output Console Messages `debug`

Enable console output messages.