ActiveField - QuickField API help

QuickField Student Edition free download     Contacts

ActiveField Technology

Objects Overview

Hierarchy Chart

How to Start: Application Object

How to work with Problems

How to work with Model

How to work with Data

How to Analyze Results

Objects

Properties

Methods

C-Shaped Magnet

Lesson 1: Using the existing problem

You can find the complete Mag1 Tutorial sample in the following folders:

The comments below describe writing code on Visual Basic 6.0

Working with a parametric model, generally we have to do the following:

Step 1: Creating a new Visual Basic project

Starting step with a new Visual Basic project is very similar to that you always do when starting any new project. If you work with MS Visual Basic 6.0, you run the Visual Basic and chose a New Standard EXE option from the New Project dialog appears.

The new project contains one Form module is created. In this lesson we will create a very simple project with minimal user interface. So we put all the code into the Form_Load () procedure

Sub Form_Load ()
    ' We will write our code here
End Sub

The Form_Load () procedure will be called by VB framework just after our application starts before the form appears on the screen.

If you prefer to use Visual Basic for Application that is included in Microsoft Office suit, first run your favorite MS Office application, say MS Excel. Then choose Tools->Macro->Visual Basic Editor command or simply press Alt+F11

There is no difference to what Excel object we will attach our code. For example choose to write the code in a module ThisWorkbook. Unlike the VB case, we have manually write the initial code lines as shown on the picture above.

When the project is created we have to let Basic know about the objects we will use. All the information necessary for dealing with QuickField object model is stored in the QuickField type library file called ActiveField.dll. It is already registered in your system if you have QuickField 4.3 or above installed. To include the reference to the QuickField type library choose Project->References command with VB or Tools->References in VBA. Then find the QuickField Object Library in the list and mark a field on the left of it.

Now it is a good idea to save our work. With VB we should save the project and all related files and with VBA we have to save the MS Office document which is a host for our VBA code; in our case - Magn1_VBA.xls.

Step 2: Launching QuickField application.

Now we are ready to operate with QuickField objects. The very first object we always get is QuickField.Application object. The Application object provides access to all other objects, so it is a good idea to declare it as a global level variable in our project.

Public QF As QuickField.Application

Sub MyMacro()
    ' Here we will write our code
   Set QF = CreateObject("QuickField.Application")
    QF.MainWindow.Visible = True
End Sub

The first line describes QF as a global variable holding an Application object. If the QuickField.exe is already running, the standard Visual Basic CreateObject function returns a running object. If not, it launches the new instance of QuickField.exe.

Now you can put the code above into your VB or VBA editor window and run it. For our educational purposes the most convenient way is running the code line by line in debug mode. So, choose the Debig->Step Into command or simply press F8 to execute next line of code.

If QuickField.exe was not started before or was invisible, we will see nothing on the screen. The last line of added code ensures QuickField be visible. When you execute this line QuickFied window appears on the screen. Please note what we use the Visibe property of the main QuickField window objects, which in turns is accessible by the MainWindow property of the Application object.

If you are not familiar with such concept as objects and their methods and properties, probably the best way to learn it quickly is browsing through a book or online help on Microsoft Excel programming (or any other application supports scripting in VB). You will see how a well known things like a workbook, a worksheet, and a cell can be considered as objects and how you can manipulate them.

Step 3: Open an existing QuickField documents (problem, geometric model and properties document).

When we have an Application object, open the desired QuickField document is a very straightforward task. There are several documents collection one for each document kind. Consider the following code:

Public QF As QuickField.Application

Sub MyMacro()
    ' Here we will write our code
    Set QF = CreateObject("QuickField.Application")
    QF.MainWindow.Visible = True

    ' Open the Magn1.pbm problem
    Dim prb As QuickField.Problem
    Set prb = QF.Problems.Open ("H:\QuickField\Examples\Magn1.pbm")

    End Sub

The first emphasized line declares the prb variable as an QuickField.Problem object. It becomes the newly problem loaded from the Magn1.pbm file.

An argument of the Open method is fully qualified name of the problem document. Another possibility is first setting the DefaultFilePath property to the desired folder:

QF.DefaultFilePath = "H:\QuickField\Examples"
Set prb = QF.Problems.Open ("Magn1.pbm")

Step 4: Modifying the geometric model.

Using the QuickField graphic user interface we load the model for editing from the problem tree view. With QuickField programming interface we do almost the same. The LoadModel method loads the Model document associated with the problem into QuickField and then it is accessible by the Model property.

It is worthy to put the geometric manipulation code into a separate procedure in order to call it with different parameters.

First of all we should to declare a variable as QuickField.Model to hold the Model object. Then we get the geometric model object using LoadModel method and Model property of the QuickField Problem object.

Sub MoveKeeper(prb As QuickField.Problem, _
ByVal left As Double, ByVal bottom As Double)

Dim mdl As QuickField.Model       ' Geometric model object
prb.LoadModel
Set mdl = prb.Model

'    The Shapes collection that contains
'    all the geometric enitities in the nodel and
'     provides methods for adding edges and vertices
With mdl.Shapes
    .RemoveMesh
    '    Delete the old Steel Keeper
    .LabeledAs(Block:="Steel Keeper").Delete
    '    and then build the new one:
    .AddEdge QF.PointXY(left, bottom), _
            QF.PointXY(left, bottom + skHigh)
    .AddEdge QF.PointXY(left, bottom + skHigh), _
            QF.PointXY(left + skWidth, bottom + skHigh)
    .AddEdge QF.PointXY(left + skWidth, bottom + skHigh), _
            QF.PointXY(left + skWidth, bottom)
    .AddEdge QF.PointXY(left + skWidth, bottom), _
            QF.PointXY(left, bottom)
    '    Locate the newborn block and assign label to it
    .Nearest(QF.PointXY(left + skWidth / 2, _
            bottom + skHigh / 2)).Blocks.Label = "Steel Keeper"
    .BuildMesh
End With

mdl.Save
mdl.Close

End Sub

Most of operation with model we make with the Shapes object - a collection contains all the geometric entities in the model. To make the code more readable we put some lines into the With block. There are Delete method that removes the block labeled as "Steel Keeper". Please note the way we use to locate the block: LabeledAs property returns the collection of objects with the same label - just like a mouse click on the label in a problem tree view.

Then we add four edges building the rectangular block. For dimensioning it we use left and bottom parameters (as Double) describing the block position and skWidth and skHigh module level variables hold block's dimensions. Note that AddEdge method requires two Point objects as parameters. We employ an auxiliary PointXY method of the Application object to create new Point with coordinates we need.

When the edges are built we have to locate a newborn block and assign it the name. The most convenient way to find a block is the Nearest property returns the nearest Block, Edge and Vertex to the given point. The Label property sets and returns the object's label.

Before finish with geometric model, we build the finite element mesh (BuildMesh method) and then save and close the model document.

Step 5: Modifying the physical properties.

Let as imagine what we have to study the influence of the coercive force of ALNICO magnet on the mechanical force. In that case we have to modify label properties. Here you can see a procedure setting given value of coercive force to both magnet labels: "ALNICO up" and "ALNICO down".

Sub SetCoerciveForce(prb As QuickField.Problem, ByVal Hc As Double)
    '    Variables for holding the label and it contents
    Dim lab As QuickField.Label
    Dim labCnt As LabelBlockMS

    '    Get the desired label
    Set lab = prb.Labels(qfBlock).Item("ALNICO up")
    '    Get label's content for editing
    Set labCnt = lab.Content
    '    Modify contents
    labCnt.Coercive = QF.PointRA(Hc, PI / 2)
    '    Put modified contnts back to the label
    lab.Content = labCnt

    '    Do the same with another label
    Set lab = prb.Labels(qfBlock).Item("ALNICO down")
    Set labCnt = lab.Content
    labCnt.Coercive = QF.PointRA(Hc, -PI / 2)
    lab.Content = labCnt
    '    Save the data document
    lab.DataDoc.Save
End Sub

The most important object here are the Label object and its contents, in our case the LabelBlockMS. To modify some physical data we have to find the label in one of Labels collection, get it contents using Contents property, modify properties provided by the Contents object, and finally put it back into the Label object.

The exact type of the Contents object depends upon the kind of QuickField problem (electrostatic, magnetostatic and so on) and geometric object the label is applied to (block, edge or vertex). In our case we are working with block labels for magnetostatic problem, so our contents object is of the LabelBlockMS type.

When finish editing the labels we should save the corresponding data document. Each label knows which document it belongs to: use the DataDoc property.

Step 6: Solving the problem.

When the model and data are ready and corresponding documents have been saved, it's time to start solving. The simplest way to do it is using SolveProblem method of the Problem object. It is a good idea to check if the model and data are ready for solving by the CalSolve property, which returns True if everything seems okay. The Solved property let us known whether the problem is solved.

If prb.CanSolve Then prb.SolveProblem
If prb.Solved Then prb.AnalyzeResults

This approach is quite enough if the solving time is rather short. When the solving process lasts for several minutes or more, you probably want your application to do something else at the same time. In such situation you can use the asynchronous version of the SolveProblem method:

prb.SolveProblem True

Here we set the NoWait parameter as True instead of its default value False. In such case the SolveProblem method returns control just after the solving process started. You can also have more control for the separate solving process by the special SolvingState object:

Dim state As QuickField.SolvingState
Set state = prb.SolveProblem(True)

Step 7: Analyzing result: evaluating local and integral quantities.

When the problem is solved we can start the postprocessor for viewing and analyzing results. To start the postprocessor use the AnalyzeResults method of the Problem object. After that we can get a Result object gives access to all other postprocessing objects. Result object maintains the collection of postprocessor windows. Among them are FieldWindow objects for the field picture, XYPlotWindow for xy-charts and TableWindow for tabulating of field quantities along the contour.

As with graphical user interface we can build a Contour in the FieldWindow, which can be used for calculating integral quantities, viewing the xy-charts and tabulating.

We put all the code concerning the force calculation in the CalculateForce function:

    ..........
If prb.Solved Then prb.AnalyzeResults
force = CalculateForce(prb.Result, xPos, yPos)
    ...........

Function CalculateForce(res As QuickField.Result, _
                ByVal left As Double, ByVal bottom As Double) As Double
    Dim win As FieldWindow
    Set win = res.Windows(1)
    With win.Contour
        .AddLineTo QF.PointXY(left - 5, bottom - 0.5)
        .AddLineTo QF.PointXY(left + skWidth + 5, bottom - 0.5)
        .AddLineTo QF.PointXY(left + skWidth + 5, bottom + skHigh + 5)
        .AddLineTo QF.PointXY(left - 5, bottom + skHigh + 5)
        .AddLineTo
    End With
    CalculateForce = res.GetIntegral(qfInt_MaxwellForce).Abs
End Function

Here we get a first field picture window from the Result object (the active window is always a first one in the collection) and build the Contour in it, surrounding the steel keeper. To add a line to contour we use the AddLineTo method. The last AddLineTo with no parameters closes the contour.

Having a closed contour we can calculate the force acting on the body(-es) inside it. For this we use a GetIntegral method of the Problem object. It returns an integral quantity as Quantity object that wraps physical values of several types. The Abs property of the Quantity object return its absolute value (magnitude).

Conclusion

Now our code is almost complete. To do it more living we make a simple form allowing to enter initial and final keeper position, moving step and coercive force of the magnet.

When the user clicks the Start button, the DoCalculation procedure is called:

Public Sub DoCalculation(Hc As Double, _
        Ymin As Double, YMax As Double, Step As Double)
    Set QF = CreateObject("QuickField.Application")
    QF.MainWindow.Visible = True
   
        ' Open the Magn1.pbm problem
    Dim prb As QuickField.Problem
        ' The Magn1 files are assumed
        ' to be situated in Magn1 subfolder under
        ' your VB project folder
    QF.DefaultFilePath = VB.App.Path & "\Magn1"
    Set prb = QF.Problems.Open("Magn1.pbm")

    '    Modifying the physical properties
    '    see Step 5
    SetCoerciveForce prb, Hc

    Dim yPos As Double, xPos As Double ' Keeper position
    Dim force As Double ' Mechanical force
    Dim i As Integer ' Loop counter
    For i = 1 To (YMax - Ymin) / Step + 1
        ' Modify the steel keeper position
        xPos = XposBase
        yPos = YposBase + Ymin + Step * (i - 1)
            ' Modifying the geometric model.
            ' see Step 4
        MoveKeeper prb, xPos, yPos

            ' Solving the problem
            ' see Step 6
        If prb.CanSolve Then prb.SolveProblem
        If prb.Solved Then
                ' Analyzing result
                ' see Step 7
            prb.AnalyzeResults
            force = CalculateForce(prb.Result, xPos, yPos)
        End If
            ' Print line to the screen
        MainDialog.DisplayStepResult yPos, force
    Next

        ' Finish the QuickField session
    QF.Quit
    Set QF = Nothing
End Sub

The only thing we have newer discuss is finishing the QuickField session. It is done by the Quit method of the Application object that works in almost the same way as File->Exit menu command.