APDL Math–Access to the ANSYS Solver Matrices with APDL

Categories:

APDL Math.  It is one of the most powerful, uber-user, deep down under the hood, wrapping your hands around the neck of what FEA is, capabilities in the ANSYS Mechanical APDL (MAPDL) solver.  And most users don’t even know it is there.  It kind of snuck in over time, with the developers adding more and more capability each release.  Now it gives you access that you needed custom FORTRAN code to get to in the past… or NASTRAN DMAP, which is really something none of us ever want to do.

There is a lot of capability in this tool. This posting is just going to cover the basics so that you know what the tool can be used for in case you need it in the future, and hopefully motivate some of you to take a long look at the help.

What is APDL Math?

It is an extension to the APDL command language that drives MAPDL.   Although it runs in a different workspace (chunk of memory in the ANSYS database) it talks to standard APDL by importing and exporting APLD arrays (vectors or matrices).  It consists, at R14, of 18 commands that can be executed at the /SOLU level at any time.  All of the commands start with a * character and look and act like standard APDL commands.

APDL Math is a tool for users to do two things: 1) get access to view, export or modify matrices and vectors created by the solver, and 2) to control import or modify matrices and vectors then solve them.  The most common uses we have seen is the exporting of a matrix from ANSYS for use in some other program, usually Matlab.  The other is working with sub-structure matrices.

The entire tool is documented in the Mechanical APDL section of the help under  // ANSYS Parametric Design Language Guide // 4. APDL Math.

The Commands

Below is a list of the APDL math commands.  As usual, you really need to read the manual entries to get the full functionality explained.  Just like parameters and arrays in APDL, the matrices and vectors in APDL Math use names to identify them.  Note that you have a set of commands to create the matrix/vector you want, which includes reading from a file or importing an APDL array.  then you have commands to do basic matrix/vector math like multiply, find dot products, and do Fast Fourier Transformations.  Then there are solver commands.

Commands to create and delete matrices and vectors
*DMAT, Matrix, Type, Method, Val1, Val2, Val3, Val4, Val5
Creates a dense matrix that is complex, double or integer. You can allocate it, resize an existing matrix, copy a matrix, or link to a portion of a matrix. You can also import from a file or an APDL variable.
*SMAT, Matrix, Type, Method, Val1, Val2, Val3
Creates a sparse matrix. Double or Complex, copied or imported.
*VEC, Vector, Type, Method, Val1, Val2, Val3, Val4
Creates a vector. Double, complex or integer. Similar arguments to *DMAT.
*FREE, Name,
Deletes a matrix or a solver object and frees its memory allocation. Important to remember to do.
Commands to manipulate matrices
*AXPY, vr, vi, M1, wr, wi, M2
Performs the matrix operation M2= v*M1 + w*M2.
*DOT, Vector1, Vector2, Par_Real, Par_Imag
Computes the dot (or inner) product of two vectors.
*FFT, Type, InputData, OutputData, DIM1, DIM2, ResultFormat
Computes the fast Fourier transformation of the specified matrix or vector.
*INIT, Name, Method, Val1, Val2, Val3
Initializes a vector or dense matrix. Used to fill vectors or matrices with zero’s, constant values, random values, or values on the diaganol.
*MULT, M1, T1, M2, T2, M3
Performs the matrix multiplication M3 = M1(T1)*M2(T2).
*NRM, Name, NormType, ParR, Normalize
Computes the norm of the specified vector or matrix.
*COMP, Matrix, Algorithm, Threshold
Compresses the columns of a matrix using a specified Singular value decomposition algorithm (default) or Modified Gram-Schmidt algorithm
Commands to perform solutions
*LSENGINE, Type, EngineName, Matrix, Option
Creates a linear solver engine and assignes a name to be used when you want to execute the solve. Does Boeing sparse, MKL sparse, LAPACK or Distributed Sparse.
*LSFACTOR, EngineName, Option
Performs the numerical factorization of a linear solver system.
*LSBAC, EngineName, RhsVector, SolVector
Performs the solve (forward/backward substitution) of a factorized linear system.
*ITENGINE, Type, EngineName, PrecondName, Matrix, RhsVector, SolVector, MaxIter, Toler
Performs a solution using an iterative solver.
*EIGEN, Kmatrix, Mmatrix, Cmatrix, Evals, Evects
Performs a modal solution with unsymmetric or damping matrices.
Commands to output matrices
*EXPORT, Matrix, Format, Fname, Val1, Val2, Val3
Exports a matrix to a file in the specified format. Supports Matrix Market, ANSYS SUB, DMIG, Harwell-Boeing and ANSYS EMAT. Also used to put values in an APDL array or print in a formated way to a postscript file.
*PRINT, Matrix, Fname
Prints the non-zero matrix values to a text file.
Useful APDL Commands
/CLEAR, Read
Wipes all APDL and APDL Math values from memory
WRFULL, Ldstep
Stops solution after assembling global matrices. Use this to make matrices you need when you don’t want a full solve
/SYS, String
Executes an operating system command. This can be used in APDL Math to do some sort of an external operation on a matrix you wrote out to a file, like running a matlab script. After execution the matrix can be read back in and used.

How You Use APDL Math

When using APDL math you should follow some basic steps.  I’m always a big proponent of the crawl-walk-run approach to anything, so I also recommend that you start with small, simple models to figure stuff out.

First Step: Know the Math

imageThe first step, or maybe the zero’th, is to understand your math.  If you charge in and start grabbing the stiffness matrix from the .FULL file and changing values, who knows what you will end up with. Chart out the math you want to do on paper or in a tool like Mathematica.

Then makes sure that you understand the math in ANSYS, and that includes the files being used by ANSYS.  A good place to look is in the Programmer’s Manual, Chapter 1 lists the various files and what is in them.  It might also not be a bad idea for you to crack open the theory manual  We all know that ANSYS solve Kx = F, but how, and what matrices and vectors are used.  Section 17.1 explains the static analysis approach used, with lots of links to more detailed explanations.

Second Step: Create your Matrices/Vectors

Since the whole point of using APDL math is to do stuff with Matrices/Vectors, you need to start by creating them.  Note that we are not doing anything with APDL Math yet.  We are using APDL, ANSYS, or an external program to get our matrix/vector so that we can then get it into APDL Math.. There are three types of sources you can get matrices/vectors from:

  1. Use APDL to create an array.  *DIM, *SET, *VREAD, *MOPER, etc…
  2. Use ANSYS to make them as part of a solve, or as part of an “almost solve” using WRFULL.  You can read the .FULL, .EMAT, .SUB, .MODE or .RST
  3. Get a file from some other source and put it into a format that APDL Math can read. It supports Harwell-Boeing, Matrix Market, or NASTRAN DMIG format as well as APDL Math’s own format.

Third Step: Get the Matrices/Vectors into APDL Math

Using *DMAT, *SMAT, and *VEC you convert the APDL array, ANSYS file, or external format file into a matrix or a vector.  You can also use *INIT to make one from scratch, filling it with constants, zeros, random numbers or by setting the diagonal or anti-diagonal  values.

Fourth Step: Manipulate the Matrices/Vectors

In this step you can modify matrices in a lot of different ways.  The simplest is to use *MULT or *AXPY to do math with several matrices/vectors to get a new matrix/vector.

Another simple way to change things is to simply refer to the entries in the matrix using APDL.  As an example, to change the damping at I=4 and J =5 in a damping matrix called dmpmtrx just use dmpmtrx(4,5) – 124.321e4.

You can take that one step further and use the APDL operators that work on arrays like *SET, *MOPER, *VGUN and whatever *DO loops you need.

If you can’t do the modification you need in APDL or APDL Math, then you can use *EXPORT to write the matrices out and use an external tool like matlab or Mathematica to do your manipulation. Of course you then use *DMAT with an IMPORT argument to read the modified matrix/vector back inside.

Fifth Step: Use the Matrix

Now it is finally time to use your matrices/vectors.  The most common use is to bundle it up in a substructure matrix (*EXPORT,,SUB) and use it in a solve.  What is great about this is that you can also (I know, we don’t want to use the N-word) save the file as a NASTRAN substructure and give it to that annoying DMAP guru who insists that NASTRAN is the only structural analysis code in the world.  He gets his file, and you get to use ANSYS.

You can also solve using APDL Math.  This can require multiple steps depending on what you want to do. A typical solve involves using the *LSENGINE command to define how you want to solve, then factor your matrix with *LSFACTOR, then solve with *LSBAK.

There are also ways to continue a solve in ANSYS after changing the EMAT file.  Unfortunately my plans to do an example of this have been thwarted and ANSYS did not provide one, so I’m not 100% sure on the steps required.  But a LSSOLVE that does not force ANSYS to recreate the matrices should work.  Maybe a topic for a future posting.

Other Stuff to Know About

There is a lot more too this, and the help is where you can learn more.  But a few things everyone needs to be ware of are listed here.

DOF Order

A key area where people have problems is understanding how the DOF’s in your matrix or vector are ordered. This is because ANSYS reorders things for efficiency of memory and solve.  The nice thing is that ANSYS stores a map in the full file that you can use to convert back and forth using the *MULT command.

Please read section 4.4 ( // ANSYS Parametric Design Language Guide // 4. APDL Math // 4.4. Degree of Freedom Ordering) in the manual. They have a great description and some examples.

Just remember to remember to deal with DOF ordering.

Limitations

This is still a new tool set and as users apply it to real world problems, they are adding functionality.  Right now there are some limitations.

  • The biggest is that that all of this works on linear matrices.  So you have to be working on a linear problem. Material or geometric non-linarites just don’t work.  This makes perfect sense but may be one of those things some users might not figure out till they have invested some serious time.
  • You can not modify a sparse matrix in APDL Math.  You have to write it out using *EXPORT, modify it with something like matlab, then read it back in with *SMAT.
  • *MULT can not be used to multiply two sparse matrices. One or both must be dense.  the result is always dense.
  • The BCS, DSS and DSP solves only work with sparse matrices. Only the LAPACK solver works for a dense matrix.

imageReal and Imaginary

Most of the features in APDL math work with matrices that have imaginary terms in them. Be careful and read the help if you are using complex math, it can get tricky.  Especially read 4.3 on how to specify a position in a matrix for real or imaginary numbers.

Examples

There are not a lot out there.  The manual has some in section 4.7.  Take a look at these before you do anything. If you can not find a specific example, contact your technical support provider and see if they have one, or if they can ask development for one.

Give it a Shot, and Share

This is a new feature, and a power user feature.  So what is happening is some very smart people are doing some very cool things with it, and not sharing.  It is very important that you share your effort with your Channel Partner or ANSYS, Inc so that they can not only see how people use this tool, but also modify the tool to do even more cool things.

It would also be cool if you posted what you do on XANSYS for the masses to see.  Very cool.

Categories

Get Your Ansys Products & Support from the Engineers who Contribute to this Blog.

Technical Expertise to Enable your Additive Manufacturing Success.

PADT’s Pulse Newsletter

Keep up to date on what is going on at PADT by subscribing to our newsletter.


By submitting this form, you are consenting to receive marketing emails from: . You can revoke your consent to receive emails at any time by using the SafeUnsubscribe® link, found at the bottom of every email. Emails are serviced by Constant Contact

Share this post:

Upcoming Events

09/27/2023

2023 AZ Bio Awards

09/26/2023

Experience Stratasys Truck Tour - Houston

09/22/2023

AIAA Rocky Mountain Section Technical Symposium 2023

09/22/2023

Experience Stratasys Truck Tour - Dallas, TX

09/21/2023

Accelerating the Energy Transition through Simulation

09/20/2023

3D Printing vs. CNC Machining - Webinar

09/13/2023

Maxwell Updates in Ansys 2023 R2 - Webinar

09/12/2023

Sandia Science & Technology Park 25th Anniversary

09/12/2023

Experience Stratasys Truck Tour - Tempe, AZ

09/08/2023

26th Annual New Mexico Flying 40 Awards

09/08/2023

New Mexico Tech Summit

09/07/2023

New Mexico Tech Summit

08/30/2023

Structures Updates in Ansys 2023 R2 (1) - Mechanical, Post & Graphics

08/23/2023

Improved Injection Molding with Additive - Webinar

08/22/2023

SPIE Optics & Photonics Exhibition 2023

08/16/2023

Fluids Updates in Ansys 2023 R2 - Webinar

08/04/2023

Experience Stratasys Truck Tour - Salt Lake City, Utah

08/01/2023

Experience Stratasys Truck Tour - Denver Colorado

07/26/2023

Solving Supply Chain Issues with Additive - Webinar

07/25/2023

Arizona Tech Leadership Golf Tournament

07/24/2023

Arizona Tech CEO Leadership Retreat

07/19/2023

System Automation & Optimization Updates in Ansys 2023 R1 - Webinar

07/13/2023

2023 AEROSPACE, AVIATION, DEFENSE AND MANUFACTURING CONFERENCE

07/12/2023

Materials Updates in Ansys Granta 2023 R1 - Webinar

06/30/2023

Turbo Expo 2023

06/29/2023

Turbo Expo 2023

06/28/2023

Turbo Expo 2023

06/28/2023

Revolutionize Packaging Design with Additive - Webinar

06/27/2023

Turbo Expo 2023

06/27/2023

2023 E-MOBILITY AND CLEAN ENERGY SUMMIT

06/26/2023

Turbo Expo 2023

06/21/2023

Optics Updates in Ansys 2023 R1 - Webinar

06/07/2023

LS-DYNA Updates in Ansys 2023 R1 - Webinar

05/31/2023

Driving Automotive Innovation with Additive - Webinar

05/24/2023

Hill Air Force Base Tech Expo

05/24/2023

Structural Updates in Ansys 2023 R1 (3) – Structural Optimization & Ex

05/23/2023

CROSSTALK 2023: Emerging Opportunities for Advanced Manufacturing Smal

05/10/2023

Signal & Power Integrity Updates in Ansys 2023 R1 - Webinar

04/26/2023

Additive Manufacturing Updates in Ansys 2023 R1 - Webinar

04/20/2023

38th Space Symposium Arizona Space Industry

More Info

04/19/2023

38th Space Symposium
Arizona Space Industry

04/19/2023

Additive Aids for Manufacturing - Webinar

04/18/2023

38th Space Symposium
Arizona Space Industry

04/17/2023

38th Space Symposium

04/13/2023

Venture Madness 2023

04/12/2023

Fluid Meshing & GPU-Solver Updates in Ansys 2023 R1 - Webinar

03/29/2023

8th Thermal and Fluids Engineering Conference

03/29/2023

Structural Updates in Ansys 2023 R1 - Composites, Fracture & MAPDL

03/28/2023

8th Thermal and Fluids Engineering Conference

03/27/2023

8th Thermal and Fluids Engineering Conference

03/26/2023

8TH Thermal and Fluids Engineering Conference

03/24/2023

Arizona BioPreneur Conference | Spring 2023

03/22/2023

2023 Arizona MedTech Conference

03/22/2023

Optimize Jigs & Fixtures with Additive - Webinar

03/15/2023

3D Design Updates in Ansys 2023 R1 - Webinar

03/08/2023

Competitive Advantages of 1D/3D Coupled Simulation - Webinar

03/01/2023

High Frequency Updates in Ansys 2023 R1 - Webinar

02/22/2023

Additive Advantages in Aerospace - Webinar

02/15/2023

Structural Updates in Ansys 2023 R1 (1) - Webinar

02/09/2023

IME 2023: MD&M | WestPack | ATX | D&M | Plastek

02/08/2023

IME 2023 MD&M | WestPack | ATX | D&M | Plastek

02/07/2023

IME 2023 MD&M | WestPack | ATX | D&M | Plastek

01/27/2023

Arizona Photonics Days, 2023

01/26/2023

Arizona Photonics Days, 2023

01/26/2023

TIPE 3D Printing | 2023

01/26/2023

Venture Cafe Phoenix Talent Night - Job Fari

01/26/2023

VFS 2023 Autonomous/Electric VTOL Symposium

01/25/2023

Arizona Photonics Days, 2023

01/25/2023

Building A.M.- Utah: Kickoff!

01/25/2023

TIPE 3D Printing | 2023

01/25/2023

VFS 2023 Autonomous/Electric VTOL Symposium

01/24/2023

VFS 2023 Autonomous/Electric VTOL Symposium

01/24/2023

TIPE 3D Printing | 2023

01/18/2023

2023 AZ Tech Council Golf Tournament

12/21/2022

Simulation Best Practices for 5G Technology - Webinar

12/14/2022

Digital Twins Updates in Ansys 2022 R2 - Webinar

12/08/2022

Tech the Halls - AZ Tech Council Holiday Mixer

12/07/2022

Electric Vehicle and Other Infrastructure Update Panel

11/30/2022

SPEOS Updates in Ansys 2022 R2 - Webinar

11/23/2022

Simulation Best Practices for Electronics Reliability - Webinar

11/16/2022

Discovery Updates in Ansys 2022 R2

11/10/2022

VentureCafe Phoenix Panel: Venture Capital in AZ

11/08/2022

2022 GOVERNOR’S CELEBRATION OF INNOVATION AWARDS + TECH SHOWCASE

11/03/2022

VentureCafe Phoenix Panel: Angel Investment in AZ

11/02/2022

High & Low Frequency Electromagnetics Updates in Ansys 2022 R2

10/26/2022

Simulation Best Practices For Chip-Package-System Design & Development

10/20/2022

Nerdtoberfest 2022

10/19/2022

2022 Southern Arizona Tech + Business Expo

10/19/2022

LS-DYNA Updates in Ansys 2022 R2 - Webinar

10/17/2022

Experience Stratasys Truck Tour - Clearfield Utah

10/14/2022

ASU School of Manufacturing Systems and Networks - Formal Opening Cele

10/14/2022

Experience Stratasys Truck Tour - Midvale Utah

10/12/2022

Experience Stratasys Truck Tour - Littleton Colorado

10/06/2022

Fluids Updates in Ansys 2022 R2 - Webinar

10/05/2022

Experience Stratasys Truck Tour - Colorado Springs

09/29/2022

White Hat Life Science Investor Conference - 2022

09/28/2022

2022 AZBio Awards

09/28/2022

Simulation Best Practices for Rotating Machinery Design & Development

09/21/2022

ExperienceIT NM 2022

Search in PADT site

Contact Us

Most of our customers receive their support over the phone or via email. Customers who are close by can also set up a face-to-face appointment with one of our engineers.

For most locations, simply contact us: