Peeling Away the *VMASK

vmask-icon2One way to really unleash the power of APDL is to become familiar, and ultimately fluent, with array parameters. The APDL student will quickly learn that array manipulation involves heavy use of the *V commands, which are used to operate on vectors (single columns of an array). These commands can be used to add two vectors together, find the standard deviation of a column of data, and so on. *V commands consist of what I like to refer to as “action” commands and “setting” commands. The action commands, such as *VOPER, *VFILL, and *VFUN * have their own default behaviors, but these defaults may be overridden by a preceding setting command, such as *VABS, *VLEN, or *VMASK.

*VMASK is one of the most useful, but one of the most difficult to understand, *V command. At its essence it is a setting command that directs the following action command to a “masking” array of true/false values. Only cells corresponding to “true” values in the masking array are considered for the array being operated on in the subsequent action command.

For example, a frequently used application of *VMASK is in the compression of an array—for instance to only include data for selected entities. The array to be compressed would consist of data for all entities, such as element numbers, x-locations for all nodes, etc. The masking array would consist of values indicating the select status for the entities of interest: 1 for selected, –1 for unselected, and 0 for not even in the model to begin with. Only array cells corresponding to a masking array value of 1 would be included in the compression operation, with those corresponding to a value or 0 or –1 being thrown out. Here is a slide from our APDL training class that I hope illustrates things a little better.


Take the class or buy the manual (and review it at Amazon, please!)

What we’ve learned so far is that the masking array contains a list of true/false (or not true) values to refer to when performing its vector operation. But actually, it’s much more general than 1, 0, and –1. What *VMASK does is include cells corresponding to all positive numbers in the masking array (not just +1) and exclude cells corresponding to all values less than or equal to zero in the masking array (not just 0 and            -1), which broadens the possibilities for how *VMASK can be handy.

Everything I’ve used *VMASK for up to this point in my career has involved array compression, and I figured I’d be put out on a sweep meshed ice floe into a sea of CFD velocity streamlines (that’s what happens to old CAE engineers; you didn’t know that?) before I came up with anything else. However, I recently ran into a situation where I needed to add up just the positive numbers in an array. I was about to construct an algorithm that would test each individual number in the array to see if it was positive and, if so, add it to the total. It would’ve been cumbersome. Then I came up with a much less cumbersome approach: use the array as it’s own masking array and then perform the addition operation. Let’s look at an example.

Take the following array:


The sum of all values in the array is 1.5 whereas the sum of just the positive values is 11.5. What’s the most efficient way to have APDL calculate each?

In the case of summing all values in the array, it’s easy, just simply execute


which gives you


But what about summing just the positive values? That’s easy, just use SUM_EXMPL as its own masking array so that only the positive values are included in the operation.




Boo yeah

Now why was I doing this? I had to create a macro to calculate total nodal loads for an unconstrained component in just the positive direction (to ignore the loads counteracting in the negative direction), and this was my approach. Feel free to download the macro: facelds.mac and try it out yourself.