Geometries

You can include geometries in text-based simulations, either by importing existing geometries or creating them in your prefile.

Creating Geometries

One can create primitives and perform operations on them, just as in the visual setup. By importing the geometry macro as detailed above, one gets a number of predefined primitives, as well as functions that can be used to perform operations on these primitives, or to create custom shapes.

Along with the creation of primitives and/or functionally-defined shapes, the following operations will be detailed herein:

  • Moving and rotating shapes

  • Advanced filling and voiding

  • Making your own primitives

Primitives

The geometry macro includes a number of primitives, including some that are available in visual setup as well as ones that are unique to the macro. Primitives that are also found in visual setup are as follows:

  • geoBoxP

  • geoCylinderXP

  • geoPipeXP

  • geoConeXP

  • geoSphereXP

  • geoTorusX

The primitives that are unique to the macro are below.

  • geoQuadrilateralSlabXP

  • geoHemiSphereXP

  • geoBiParabolicSlabXP

  • geoTriangleSlabXP

  • geoRndCylinderXP

  • geoRndRectangleSlabXP

  • geoEllipsoid

  • geoHemiEllipsoidXP

  • geoEllipticalCylinderXP

  • geoEllipticalConeXP

To use these primitive functions, one must assign a geometry name to appear on the first in the parentheses, followed by the primitive function and values you’ve entered for the parameters. Below is an example showing the creation of a hollow cylinder with the geoCylinderXP function, using the described syntax.

fillGeoExpression(hollowCylinder, geoPipeXP(x,y,z,INNER_RADIUS,RADIUS,LXO))

The parameters used above are as follows, though one could also just input numerical values rather than parameters or constants:

  • x

  • y

  • z

  • INNER_RADIUS

    Inner radius of the cylinder.

  • RADIUS

    Outer radius of the cylinder.

  • LXO

    Length of cylinder in the axial direction (x).

The parameters required for each of the primitive functions in the macro are detailed fully in the section on the macro file in Reference.

Moving and Rotating Shapes

The above shapes are defined around points of symmetry; cylinders and spheres are centered around the origin, and rectilinear shapes begin at the origin and extend out in the x-direction.

However, one can provide offsets in any direction–x, y, or z–by subtracting the desired offset from the respective variable parameter. For instance,

fillGeoExpression(hollowCylinder, geoPipeXP(x-0.03,y+0.04,z,INNER_RADIUS,RADIUS,.1))

would result in our cylinder being offset from the origin by 3 centimeters in the x-direction and 4 centimeters in the y-direction. Its length in the z-direction would be 10 centimeters.

One can also rotate the shape so that it is centered about a different axis. For example, if the cylinder needed to be centered about the z-axis, the .pre file input would be:

fillGeoExpression(hollowCylinder, geoPipe(z,x,y,INNER_RADIUS,RADIUS,.1))

Notice that the x, y, and z entries from before have changed so that they now are z, x, and y. The first entry is the axial direction.

You can mimic the Boolean operations that are available with visual setup by using the

voidGeoExpression fillGeoExpression

functions with the primitives you have already defined in your simulation. The first example below walks through joining two primitives, one being a box named box1 and the other being our hollowCylinder.

fillGeoExpression(box1, hollowCylinder)

Advanced Filling and Voiding

There are two main methods of creating custom shapes, function-defined and primitive-based.

The function-based way of creating shapes involves first creating functions that describe your desired shapes, which can be done through implementation of Heaviside functions. You can then use these functions as input for either the fillGeoExpression or voidGeoExpression functions. We can use this process as an alternate means of building our hollow cylinder from before, beginning with the function definition:

<function cylinderFunc>
  H(-INNER_RADIUS^2 + x^2 + y^2)*H(RADIUS^2-x^2-y^2)
</function>

where the INNER_RADIUS and RADIUS parameters are the same as those used in the hollowCylinder primitive above.

The geometry itself can then be defined by simply determining a name as the first parameter–here, we have chosen hollowCylinder again–and then invoking the function defined above.

fillGeoExpression(hollowCylinder, cylinderFunc(x,y,z))

The voidGeoExpression function, on the other hand, designates a certain volume of space to be removed from another. For example, this can be applied to a box, which can then be “subtracted” from a larger box. These operations are implemented in a macro, whose name is that of the overall geometry.

<macro boxes>
  voidGeoExpression(smallBox, geoBoxP(x,y,z,0.05,0.05,0.05))
  fillGeoExpression(bigBox, geoBoxP(x,y,z,0.1,0.1,0.1))
</macro>

Making Your Own Primitives

If you want to make your own primitive that can then be used repeatedly in your simulation, you can define your geometry in the macro format and then call the macro from multiple places in your .pre file. For example, we can define our hollowCylinder as below:

<macro hollowCylinder>
  H(-INNER_RADIUS^2 + x^2 + y^2)*H(RADIUS^2-x^2-y^2)
</macro>

Importing Geometries

One can import both .stl and Python-defined shapes. CAD geometries can be used in conjunction with CSG primitives built in VSim.

CAD (.stl) Shapes

You can import existing shapes whose files end with the .stl extension by using the (slightly different) functions fillGeoCad and voidGeoCad. There also exists the optional function fillGeoFastCAD.

These functions’ parameters are detailed in full in the geometry macro file section, but a basic example of fillGeoCad being used to import an .stl file is given below:

fillGeoCad(hollowCylinder, hollowCylinder.stl, False, 1.0,[0 0 0])

where “hollowCylinder” is the name of the object in VSim and “hollowCylinder.stl” is the .stl file being imported. The last three entries, “False,” “1.0,” and “[0 0 0],” are default values, and as such the hollowCylinder object has imported with 1-1 scaling and no translations.

Importing a Python File

To import a Python-defined geometry, one can use the functions fillGeoPython and voidGeoPython in conjunction with a Python function that is defined in a .py file.

fillGeoPython(hollowCylinder, makeHollowCylinder)

The Python file must have the same name as the input file name and contain the function you wish you use. The function should be equal to 1 inside the geometry object and to 0 outside.