Gridtrace_Tutorial
Table of Contents
Gridtrace Tutorial
Introduction
The purpose of this tutorial is to provide explanation on how to use the class defined in xmsgridtrace to trace a given point through a velocity vector field grid. The example provided in this tutorial refers to a test case that is in the xmsgridtrace/gridtrace/XmGridTrace.cpp source file.
Example - Simple Gridtrace
This is the "hello world" example for using the gridtrace library.
This example shows how to trace a point through a simple grid. The testing code for this example is in XmGridTraceUnitTests::testTutorial. A picture of the example is shown below. Notice that the UGrid is 4 simple squares from (0,0) to (2,2) with each square having a side length of 1. The velocity vectors are mapped to the points.
Simple XmUGrid with 4 Cells and 9 Velocity Vectors x
The basic steps to trace a point through a velocity vector field are as follows:
- Create the grid
- Create the tracer from the grid
- Set up the constraints on the tracer
- Set up the velocity vectors for both time steps. Insert timesteps sequentially
- Trace the point
{
// Graph with scalar vectors indicated
// -> ->
// 6----7----8|
// | | |v
// | | |
// | | |
// ^| | |
// |3----4----5|
// | | |v
// | | |
// | | |
// ^| | |
// |0----1----2
// <- <--
// Step 1: Create the grid
VecPt3d points = {{0, 0, 0}, {1, 0, 0}, {2, 0, 0}, {0, 1, 0}, {1, 1, 0},
{2, 1, 0}, {0, 2, 0}, {1, 2, 0}, {2, 2, 0}};
VecInt cells = {XMU_QUAD, 4, 0, 1, 4, 3, XMU_QUAD, 4, 1, 2, 5, 4,
XMU_QUAD, 4, 3, 4, 7, 6, XMU_QUAD, 4, 4, 5, 8, 7};
BSHP<XmUGrid> ugrid = XmUGrid::New(points, cells);
// Step 2: Create the tracer from the grid
BSHP<XmGridTrace> tracer = XmGridTrace::New(ugrid);
// Step 3: Set up the constraints on the tracer
tracer->SetVectorMultiplier(2);
tracer->SetMaxTracingTime(-1);
tracer->SetMaxTracingDistance(-1);
tracer->SetMinDeltaTime(.01);
tracer->SetMaxChangeDistance(-1);
tracer->SetMaxChangeVelocity(-1);
tracer->SetMaxChangeDirectionInRadians(XM_PI / 4);
// Step 4: Set up the velocity vectors for both time steps. Insert timesteps sequentially
double time = 0;
// Scalars are set such that they circle around the edge of the graph in a clockwise direction
// Z component is not used in scalars
VecPt3d scalars1 = {{0, 1, 0}, {-.1, 0, 0}, {-1, 0, 0}, {0, .1, 0}, {0, 0, 0},
{0, -.1, 0}, {1, 0, 0}, {.1, 0, 0}, {0, -1, 0}};
DynBitset pointActivity;
for (int i = 0; i < 9; ++i)
{
pointActivity.push_back(true);
}
tracer->AddGridScalarsAtTime(scalars1, DataLocationEnum::LOC_POINTS, pointActivity,
DataLocationEnum::LOC_POINTS, time);
// For the second timestep scalars are doubled to indicate an increase in magnitude
VecPt3d scalars2 = {{0, 2, 0}, {-.2, 0, 0}, {-2, 0, 0}, {0, .2, 0}, {0, 0, 0},
{0, -.2, 0}, {2, 0, 0}, {.2, 0, 0}, {0, -2, 0}};
time = 20;
// Uses exact same scalars/pointActivity
tracer->AddGridScalarsAtTime(scalars2, DataLocationEnum::LOC_POINTS, pointActivity,
DataLocationEnum::LOC_POINTS, time);
VecPt3d outTrace;
VecDbl outTimes;
Pt3d startPoint = {.5, .5, 0};
double startTime = 0;
// Step 5: Trace the point
tracer->TracePoint(startPoint, startTime, outTrace, outTimes);
// show the cause for termination by calling GetExitMessage
// std::cout << tracer->GetExitMessage();
// Expected values for this simulation
VecPt3d expectedOutTrace = {{0.50000000000000000, 0.50000000000000000, 0.00000000000000000},
{0.50000000000000000, 1.2500000000000000, 0.00000000000000000},
{0.54457812566426578, 1.3391562513285316, 0.00000000000000000},
{0.61632493250262921, 1.4354984729093498, 0.00000000000000000},
{0.72535406450374607, 1.5315533661126233, 0.00000000000000000},
{0.88236797164001590, 1.6126801842666139, 0.00000000000000000},
{0.98873181403598276, 1.6331015959080102, 0.00000000000000000},
{1.0538503898747653, 1.6342606013582104, 0.00000000000000000},
{1.1249433009705341, 1.5683006835455087, 0.00000000000000000},
{1.1895097427498795, 1.3863448896225066, 0.00000000000000000},
{1.2235242118635632, 1.0588590059131318, 0.00000000000000000},
{1.2235242118635632, 0.90477286425654002, 0.00000000000000000},
{1.2005336220528682, 0.85080764250970042, 0.00000000000000000},
{1.1581790674742278, 0.79387770198395835, 0.00000000000000000},
{1.0896874578697060, 0.74131697161132859, 0.00000000000000000},
{0.98966250551038770, 0.70663752692174131, 0.00000000000000000},
{0.95806149614159530, 0.71817980325332686, 0.00000000000000000},
{0.92629620502521459, 0.77371504022050730, 0.00000000000000000},
{0.90239412753251202, 0.88917318465162865, 0.00000000000000000},
{0.89995172701803572, 1.0694875660697027, 0.00000000000000000},
{0.91503139037776327, 1.0911992829869794, 0.00000000000000000},
{0.93816744602651825, 1.1127546977629765, 0.00000000000000000},
{0.97140028507849163, 1.1309789606067331, 0.00000000000000000},
{0.99364912627842006, 1.1358370729524059, 0.00000000000000000},
{1.0071524474802995, 1.1364684019706512, 0.00000000000000000},
{1.0223447138862345, 1.1280655805979485, 0.00000000000000000},
{1.0369737821057583, 1.0971462034407997, 0.00000000000000000},
{1.0467397711865176, 1.0371377237101163, 0.00000000000000000},
{1.0467397711865176, 0.96499504248441559, 0.00000000000000000},
{1.0390576209755447, 0.95473758230148376, 0.00000000000000000},
{1.0276444556154691, 0.94488898976070590, 0.00000000000000000},
{1.0208791233912420, 0.94149540451099356, 0.00000000000000000}};
VecDbl expectedOutTimes = {
0.00000000000000000, 0.37500000000000000, 0.82499999999999996, 1.3649999999999998,
2.0129999999999999, 2.7905999999999995, 3.2571599999999994, 3.5370959999999991,
3.8730191999999990, 4.2761270399999987, 4.7598564479999981, 5.3403317375999979,
6.0369020851199977, 6.8727865021439971, 7.8758478025727969, 9.0795213630873555,
9.4406234312417237, 9.8739459130269651, 10.393932891169255, 11.017917264940003,
11.766698513464901, 12.665236011694777, 13.743481009570628, 14.390428008296139,
14.778596207531445, 15.244398046613812, 15.803360253512654, 16.474114901791264,
17.279020479725595, 18.244907173246794, 19.403971205472232, 20.000000000000000};
TS_ASSERT_DELTA_VECPT3D(expectedOutTrace, outTrace, .0001);
TS_ASSERT_DELTA_VEC(expectedOutTimes, outTimes, .0001);
} // XmGridTraceUnitTests::testTutorial
