FEMAP API tutorial

I really like writing scripts that do stuff for me, so this post was a long time coming! I was just waiting for a time when I will be writing some FEMAP tools for my office. And finally, the time is now!

Automating work in FEMAP (or any other FEA package) is a great idea! It will not only speed you up but also help in avoiding mistakes in repeatable tasks! Here, we will focus not only on the “How” but also “What” and “When” to automate with API for Femap!

The technical part (the “How”) starts a bit down below. But before we get there, there are some things I think you should know… or at least things that I regret I didn’t know!

After all, there is a reason I was waiting for the right time to write APIs!

When to automate?

This will be brief and may seem irrelevant. But I think that this is critical. If you wonder how I know that, it’s easy! I wasted hundreds of hours building tools in the past that I never really used…

This is why I never start writing APIs just as we enter a new design domain. It’s just too early, and I won’t predict accurately what is the best approach to things, and how to automate it!

This is why I try to follow (more or less accurately) the following scheme:

• At the very beginning of designing something new, I’m making Excel sheets that aid design (you know, calculate loads, provide estimates, etc.). In fact, I’ve noticed this is my preferable way of learning new rules! But those first spreadsheets aren’t the best. I know full well that I will update them later.
• As we do more and more of the projects in the given space, I try to make my Excel sheets better and more useful. Last time it took me like around 10-15 projects to start working again on the spreadsheets I prepared at the start… simply because I saw lacks in them.
• When I feel I’m ready I will start working on the *process*. This usually involves a day of work and support from my team. We will discuss how the projects develop, what has to be done in what order, what can differ between projects, etc. With pressure vessels, it took us something like 30 projects to reach this stage (more or less a year from the first one we delivered)
• When the *process* is well described (I have 10-15 steps each described on a separate page) I will think about what I can automate. Of course, we will discuss this internally and rank order what is most useful (not all can be done!). This is where I am right now with pressure vessels 🙂

Why the above process is so important?

I’m an over achiever. In the past I would start in any new domain, thinking I know full well what tools I will need. Then instead of thinking how to do things better, I would work on automation from the get go.

You would not believe how many useless scripts and excell sheets I have done… thinking they will be super-useful later on!

But there is a hidden benefit there as well. Working for a year in a given space gives you a chance to see if you like it (and if there is enough work there to make it worthwhile!). All of this before you start wasting time on automating stuff!

What to automate?

This is a super short part, but trust me… you want to read this!

Automation is a tool, you are building to help you in your work. It can be a super complex multi-purpose bombastic FIX-2000… or a hammer!

Somehow, I don’t usually see people with FIX-2000 on building sites, and hammers are surprisingly still very popular.

Don’t build a FIX-IT-ALL solution! This is a complete waste of time (and I know it since I’ve built several!). It is far better to have several tools you will have to use one after another, rather than one big thing that does it all!

The more complex the thing becomes, the less you have control over it. And at a certain level, you stop using it, since you don’t trust it anymore (my Excel that calculates everything in a silo… yup I’m looking at you!).

Also, if you have one big thing… it is super-interdependent. I had to rewrite the section that calculated wind on a shell for pressure vessels even though I had one for silos. But the silos one was embedded in a huge system for silos that I have. It was so mixed with everything else, that it was just simpler to make a new one! I could have kept all the silos solutions separate… and I would save myself quite some time already…

Build small solutions

If you want to make a script that designs a hall building, don’t build it as a one-piece thing!

It is far better to make a separate module that generates geomery, then wind-load module, and snow-load module separately etc.

This way, not only you have a much higher controll over what each module does… you can also easily use them without using the others!

How to automate?

All right! We are finally here! You already have enough experience with the thing that you want to automate, that you know what tools you want. You also learned, to make small tools, not large ones!

Awesome, we are ready to roll!

What I will do here, is a tool, that automatically generates load combinations for my pressure vessel analysis.

We apply loads in separate load cases in Femap. This has several advantages:

• First of all, we can detect any issues with any given load. You know, wrongly input data, wrong load directions, etc. Since we can run an analysis with only this load – those are easy to check.
• We can use the same load several times with “combine load” tools, to build load cases that we like.

The thing is, that usually, we create the same load combinations, so it seems reasonable to have a button that says “do load combinations”! This way, we may be more or less certain that those will be done correctly!

To do something like that, I start with Femap API (Tools -> Programming -> API Programming). There is also an option for Macro Recording, but sadly it is not recorded as a VBA script, so this won’t be so useful to us.

This is a huge bummer – Abaqus records Macros as Python script (that you use in Abaqus API). So you can record clicking something, and then simply copy-paste the line to your code with changing some parameters. It won’t be so simple here!

Stage 1: First few steps

Disclaimer: As with FEA, I am almost completely self-taught when it comes to programing (ok I had some training in primary school, and I was pretty decent back then!). I don’t claim this will be elegant… but it will work to the extend that I will be able to check! That’s good enough for me!

The good thing is, that I haven’t written an API in at least 2 years… so I don’t remember much. It seems you can experiment with me!

The first thing you see, when you open the API Programming tab in FEMAP is:

Sub Main
    Dim App As femap.model
    Set App = feFemap()

End Sub

This just starts (and ends!) the API you are writing, and also “links” to your Femap model. Nothing terribly fancy, but we won’t get anywhere without that!

As I wrote before, the goal of my API is to do something with load combinations. So obviously I’m interested in finding keywords and commands that will be useful. In the Help menu, there is a programming tab… but I find the help there really hard to use. I treat this as the “last resort” thing.

Instead, I often open one of the APIs Femap comes with (your Reseller may even add a few more I’ve heard!). Those are listed as “Custom Tools” and the files are in the Femap installation folder in the API subfolder.

Just find one that sounds like something similar to what you are building… it will contain useful stuff!

Thanks to the “Bearing load on surfaces…” custom tool I found few useful lines:

Sub Main
    Dim App As femap.model
    Set App = feFemap()

    Dim Load_Set As femap.LoadSet
    Set Load_Set = App.feLoadSet

End Sub

The Dim command tells your API that the name (in this case “Load_Set”) is a parameter containing a certain type of information (here, a “thingy” defined as femap.LoadSet).

Then in Set, you actually “make it alive” as far as I understand. So you need both. Notice, that in the “Set” option I used “App” which is defined as my current Femap model just 2 lines higher).

Think about it this way: I want the Load_Set parameter I just defined to be a load set in my model. So I invoke: My_model[.]Load_Set. The dot [.] is like “go deeper and more specific” as far as I can tell (never properly learned object coding!). In essence, the idea is, that you can’t have a “load set” floating around in the void. It must be “attached” to the Femap model. Hence App.feLoadSet.

This is also why I like using Custom tools at the beginning! They already hint at things like this, and I didn’t have to search for “how to write this”!

Stage 2: Get automatic help!

Now, things start to be much easier! Since I have a load set object defined, I can see what parameters it can take. There is a really cool “helping tool” for that!

Of course, I never used load sets in my coding before, so I don’t really know what can be done to them. Let’s see then, what the options are!

When you have set things properly, after putting a dot “.” behind the parameter name displays a list of all the things you can do to it. This is the simplest way to approach this since names are more or less self-explanatory in some cases.

As you can see, there are two different types of things on the list. The ones with a green symbol (like the “PutCombination” I’ve selected) are called methods. Usually those “do something” – like define a load combination in this case!

Some methods (most actually) require some parameters. It’s all nice and dandy that we want to define a load combination… but we should say what the load factors are, and what load cases shall be included. When you open a bracket “(” after the method name, a help field with all required parameters will pop up (check the short animated example above).

I usually don’t even try to read what those parameters do if I’m not certain… I will just play around and input various numbers in, to see what will happen. Usually, it’s much quicker this way!

But! Before we start testing, we need to actually insert the load combination into our Femap model. So far we defined that we want one, but we want to “send it” to the model. Simple .put(id) method will do that. So if I want my load combination to be number 10 on the Femap tree, I will add Load_Set.put(10) at the end:

Sub Main
    Dim App As femap.model
    Set App = feFemap()

    Dim Load_Set As femap.LoadSet
    Set Load_Set = App.feLoadSet

    Load_Set.PutCombination(1,1,2.0,1)

    Load_Set.Put(10)

End Sub

This is something we could run (there is a green play button above the code in Femap), and see what will happen. You most likely noticed on the animated example, that I have already created some load cases so I have something to combine!

Stage 3: Trial (and lots of errors!)

Did you noticed, that the 3rd parameter in .PutCombination is “2.0” not “2”? Seemingly the same thing, but this makes the value seen as a “real” number! I’m sure that I could check how that works, but there is a faster way to deal with this!

Just experiment with those if something won’t work in your code! In this case, the 3rd number needs to be “2.0” otherwise the command won’t create the load combination (it will do nothing)! It was extremely easy to spot that when you run the code several times and you know that adding a “.0” can change something!

A few tires with various settings showed me, that in .PutCombination parameters are (in order):

• Overal scale factor (the same as in the Load Combination window in Femap)
• Number of how many load cases will be combined
• List of load factors for each load case (stored as “variant” which is a data type mentioned in the tooltip help)
• List of load cases to be combined (again stored as “variant”)

Pretty simple right? I mean what I did is I’ve read the tooltip help that appeared when I added “(” after the method name, and experiment a bit to confirm my suspicions (not all names were obvious to me).

I wasn’t sure what a “variant” was… so I searched for it in the help. It’s just a fancy name for an array of data. This is like a “numbered list”… Imagine you have a book (that is a variant) and on each page, you can write something. And since pages are numbered… you can ask “what is on the 12th page of the book, instead of reading the whole thing. We will get to that in a second!

This is more or less how I write code – nothing glamorous, but I get what I want in the end!

Stage 4: Getting deeper

All right, we already know something!

But for this to work, we need to deal with the “variant” thing! Help suggested this is just a data type, so let’s make 2 of those! One for the list of Load Factors, and one for the list of Load Cases.

Of course, we will have to “Dim” the parameters in the first place (that is done near the top). Notice that I’ve added a “(10)” after the name. It tells the API that the book will have 10 pages. Sometimes if you don’t define that, things won’t work properly.

Sub Main
    Dim App As femap.model
    Set App = feFemap()

    Dim Load_Set As femap.LoadSet
    Set Load_Set = App.feLoadSet

    Dim Factors(10) As Variant
    Dim Load_Cases_List(10) As Variant

    Load_Set.PutCombination(1,1,2.0,1) 
    Load_Set.Put(10)

End Sub

Then I will assign values I like to each page of the book (first 3 pages to be precise). Notice that in IT, the first page has a number “0” on it… just because they are so fancy! Page Numbers are in brackets, as you can see below and by doing “= whatever” I ask the API to write “whatever” at a selected page of my book.

Sub Main
    Dim App As femap.model
    Set App = feFemap()

    Dim Load_Set As femap.LoadSet
    Set Load_Set = App.feLoadSet

    Dim Factors(10) As Variant
    Dim Load_Cases_List(10) As Variant

    Factors(0) = 2.0
    Factors(1) = 3.0
    Factors(2) = 5.0

    Load_Cases_List(0) = 1
    Load_Cases_List(1) = 4
    Load_Cases_List(2) = 5

    Load_Set.PutCombination(1,1,2.0,1)  
    Load_Set.Put(10)

End Sub

As you can see above, the Load factor on the “0” page of the book “Factors” is 2.0. This will correspond with Load Case 1 since “1” is on the “0” page of the book “Load_Cases_List”.

The rest is simple! Instead of numbers, I’m using the names I gave to my variants when I define the .PutCombination method and I’m done!

Sub Main
    Dim App As femap.model
    Set App = feFemap()

    Dim Load_Set As femap.LoadSet
    Set Load_Set = App.feLoadSet

    Dim Factors(10) As Variant
    Dim Load_Cases_List(10) As Variant

    Factors(0) = 2.0
    Factors(1) = 3.0
    Factors(2) = 5.0

    Load_Cases_List(0) = 1
    Load_Cases_List(1) = 4
    Load_Cases_List(2) = 5

    Load_Set.PutCombination(1,3,Factors,Load_Cases_List)
    Load_Set.Put(10)

End Sub

I think that at this stage you already know that it works. As long as I will remember to have specific load cases in good places, I can automate creating all of the Load Combinations using the code above. All I need is to input proper Factors and Load Cases on good pages of their books! Of course, I can copy-paste that part of the code that does combinations several times, to make several load combinations in one go! You know, something like this:

Sub Main
    Dim App As femap.model
    Set App = feFemap()

    Dim Load_Set As femap.LoadSet
    Set Load_Set = App.feLoadSet

    Dim Factors(10) As Variant
    Dim Load_Cases_List(10) As Variant

    Factors(0) = 2.0
    Factors(1) = 3.0
    Factors(2) = 7.0

    Load_Cases_List(0) = 1
    Load_Cases_List(1) = 4
    Load_Cases_List(2) = 5

    Load_Set.PutCombination(5,3,Factors,Load_Cases_List)
    Load_Set.Put(10)

    Factors(0) = 1.5
    Factors(1) = 2.0
    Factors(2) = 3.0
    Factors(3) = 1.0

    Load_Cases_List(0) = 1
    Load_Cases_List(1) = 2
    Load_Cases_List(2) = 3
    Load_Cases_List(3) = 5

    Load_Set.PutCombination(5,4,Factors,Load_Cases_List)
    Load_Set.Put(20)


End Sub

As you can see, I’ve added the “second run” that creates an additional load combination! Notice that I’ve changed “3” into “4” in the second parameter of the .PutCombination method. This is the “amount of load cases” to be used, and the second time, I wanted to use 4 of them! This means that during the second run API will read the first 4 pages of the book (numbered 0, 1, 2, and 3). If I would leave the second parameter as 3, my load combination won’t include the 5th load case with 1.0 load factor… it’s in the book, but API would not get so far in reading the book!

Also, the final .Put(20) method has 20 not 10 as the Load Combination id. I need to have different numbers since otherwise, the last one will override the first one!

Stage 5: Making this work!

Awesome! We have the code that we want to use as an API. Sure, I will work on this later, to actually add my load combinations, but this is where this tutorial ends.

But you don’t want to have to copy-paste the code each time in Femap to make this work right?

Luckily, this is rather simple! All you need is the .BAS file with the code we just wrote together! If you click “save” in Femap (over the code in the API window), it will do it automatically. If you are writing this somewhere else (like in notepad)… just save this in a text file with the .BAS extension instead of .TXT (if you don’t know how to do it, watch this: https://www.youtube.com/watch?v=YlN9ax7yC0A).

Then copy-paste this file into your Femap installation Folder to a subfolder called “apiuser”. It’s possible that you won’t have it and there will be only “api” folder. In such a case – just create the “apiuser” folder!

Then, when you open Femap, you can go to the “Users Tools” menu, and your file name will be on the list. Just as with the custom tools – click it, and your API will run!

Where to go now?

If everything went according to the plan, you just wrote your first API. And, if you spend a few minutes to actually set the load combinations that you use the most… it will be a pretty useful one!

Sure, this is a rather simple thing, but it would be pretty hard for me to show you more in a single post. There are however a few pieces of advice I can give you:

• Don’t be scared and experiment! I haven’t lie about how I did this API. I literally had no idea how to start… and I did the same thing I always do – I searched and tried! Now you know the easiest ways to find what you are looking for! Just try – there is nothing to lose!
• Don’t build huge tools! This is the one I’ve learned the hard way! Those will cost you a lot of “life”, and in time you will realize that they don’t cover everything anyway. It’s much better to have a tool that does wind load on silos, separate one on a tank or a house, etc. If you try to build a “wind tool” that covers all the possibilities in one place… you will most likely drown in it, and it will be so complex that in the end, you won’t be sure if it even works…
• Just google for this! What we haven’t touched here are the loops (do something several times automatically), logic (if “this” then do “that”) and other similar topics. Those are not Femap specific. There are a LOT of free VBA coding resources online, and those are really easy to find as well! Just search for them, and you will find what you need!
• This is addictive – be warned! Even as I finished this small thing, I already feel the urge to sit all night and make it better! And I did spend a lot of nights playing with APIs before! Just be aware that programming has something that “sucks you in”, and having a wife that will yell at you to go to sleep is actually a good thing!

Do you want more?

I’m not sure how popular API topics in Femap will be. This is a super-specific thing after all! If you enjoyed this, and you would like more – let me know in the comments below!

I will be developing some tools in the coming weeks (as you can see I just started), so there is a chance for part 2 of this post with some additional things (or maybe even a mini-course in the future)!