# OPERA Tutorial

This page covers the design and analysis of a magnet model in the OPERA-3d software suite.

## Magnet Design Process and Tutorial

The design process is done in several steps

• In OPERA Modeler...
• Design the magnet and set initial current density
• Create any iron yokes or shielding
• Create surface and volume meshes
• Run an analysis

The analysis creates file which can be analyzed in OPERA's Post-Processor

• In the Post-Processor...
• Determine magnetic field profile through plots
• Simulate particle trajectories

What follows are the necessary steps to create and analyze the Simple Solenoid (SS) design with a simple iron yoke. This steps of this process can be used to create any model with any level of complexity. Excluded here are some features of OPERA which the EIC task force has no need for at this stage of development. Namely, modeling the force of conductors and the necessary support structure for magnets is an available feature that we do not discuss here. For more information on this and other processes please refer to COBHAM's OPERA website.

### Accessing OPERA

The EIC OPERA current install is version 14R1, and can be found in /afs/rhic.bnl.gov/eic/PACKAGES/Opera_14R1. By adding the following code to the user's shell,

setenv VFDIR /afs/rhic.bnl.gov/eic/PACKAGES/Opera_14R1
setenv VFGRAPHICS screen
setenv VECTORFIELDS_LICENSE_PATH @license.itd.bnl.gov
setenv PATH /afs/rhic.bnl.gov/eic/PACKAGES/Opera_14R1/bin:\$PATH

the user can access OPERA by typing opera_manager in their terminal provided that the user logged into an EIC node on the BNL RHIC servers. The manager window is a GUI which allows the user to view the files they have created and launch the modeler or post-processer. The manager will create a folder named opera_logs in the user's home directory. The above environment assumes a .cshrc shell. This is where any .log or .lp files will be saved. The .log and .lp files contain information on the users work/simulations. In particular, the .log file displays which models are opened, what particle trajectories are displayed, and whether or not the reference axes (x- y- z- axes) are displayed or hidden. The .lp files display the details or each model opened, the data points from magnetic field maps or the data points from a particle trajectory simulation. The opera_logs folder is also where one should install the particle plot mapping program found here. The /eic/u/ directory will be the default location for OPERA to save models, conductors, and analyzed models. The user directory will also have OPERA's bh folder copied into it. This folder contains magnetic permeability data for various materials and will be discussed further in Cell Properties and the Model Body.

There are a limited amount of licenses available for the OPERA Modeler and Post-Processor. This can lead to error messages such as

License Error
LM-X Error: (Internal: 289 Feature: OPERA_3D_MODELLER)
[NETWORK] 6200@license.itd.bnl.gov - (Err: 17) Request for more licenses than available on license server

If this happens, select the following in the OPERA Manager Window, Licensing > List Licensed Software then choose the "Opera-3d" tab and scroll down to see the current users. Using this user name, it may be possible to email or locate the user in order to discuss sharing the software.

### OPERA Modeler

OPERA Modeler is unique in that it is "unit-free". Designs are created based entirely on numbers and ratios. It's only in the Modeler Analysis and Post-Processor that units for length and magnetic field are specified. For this reason designs must be built carefully with the intended units in mind. For instance, the current designs for the eRHIC are built with mm and T for length and magnetic field values. Thus, the modeler has conductors with coordinates of order ~1000 mm and current densities of order ~10 A/mm2. How to specify the units will be discussed in Model Construction. The Modeler may be selected from the Manager window by clicking on the top menu Opera-3d > Modeller.

#### Model Construction

All OPERA bodies are created using fixed parameters. Let's consider an example, the Simple Solenoid (SS). The Create Solenoid Conductor menu may be accessed by clicking in the top menu of the Modeler window Create > Conductor > Solenoid. The solenoid's geometry has four (x, y) coordinates which determine its length, width, and height. These coordinates are specified based on the solenoid's cross-section, as can be noted in the image to the right. Below is a screen shot of the Create Solenoid Conductor > Solenoid Parameters window.

Solenoid Parameters
XP1 1000 YP1 -1200 XP2 1000 YP2 1200
XP3 1100 YP3 1200 XP4 1100 YP4 -1200
CU1 0 CU2 0 CU3 0 CU4 0

It may be noted in the above table that certain coordinates are highlighted similarly. This is obvious given the diagram, but the Create Solenoid Conductor command has no pictures associated with it, so it is important to keep in mind the orientation of the default conductor. The above Solenoid parameters specify a conductor with overall length 2400 mm, which is centered at (x, y, z) = (0, 0, 0). All OPERA bodies are centered at (x, y, z) = (0, 0, 0), unless an option to input different coordinates is presented in a creation window. This solenoid also has an outer radius of 1100 mm and an inner radius of 1000 mm, with the barrel parallel to the y-axis. All bodies created will be centered at (x, y, z) = (0, 0, 0). If the user wishes to shift their model away from this point, they may select the conductor by choosing Picking > Pick Conductors from the modeler top menu bar and use Operations > Transform > and the "Displace" radio button to move the selected body. Entering the amount of units in the proper field and the selecting "OK" will move the body. If the user selects "Apply" and then "OK" the action (displacement) will be applied twice. The "CU" options determine the curvature of the faces of the solenoid. They are not utilized in the present example. The following table describes the other windows encountered in the Create Solenoid Conductor menu and the necessary inputs to create the SS design.

 The Source Drives window allows users to set the current density of their magnet and name the magnet. Since our current density will have units of A/mm2, we see that the density has been set to -31.75 A/mm2. The default current direction is clockwise around the y-axis when the y-axis is directed towards the user. The conductor (drive) has also been named "solenoid". The "Biot-Savart current source" is the option used in our analysis, "Circuit element" is for non-magnetostatic simulations.
 Shown here is the Local Coordinate Systems window. OPERA's default orientation for solenoids (and other model bodies) places the central body axis along the y-axis (see below left). The EIC Task Force modeling prefers the barrel axis to be along the z-axis (see below right). This rotation can be accomplished in the Local Coordinate Systems window by setting theta, phi, and psi as shown or by clicking Operations > Transform > in the modeler top menu bar and choosing the "Rotate" radio button.
 The Symmetries window allows users to save computation time in constructing the models and running the analysis. This is accomplished by making one fraction of the model, and then reflecting it about the indicated planes. Although this may save time, current directions cannot be seen until the model is viewed in the post-processor, thus magnets are best constructed as a whole, or as a half with copies produced through the Operations > Copy menu.

Hitting "OK" will then create the SS solenoid with the barrel oriented along the z-axis. The next set of steps will create an iron yoke around the magnet and prepare it for analysis and the post-processor. In order to create the yoke, we must click in the top menu of the Modeler window Create > Object > Cylinder/Cone.

 The Create a Cylinder window has no separate tabs. The specifications shown the the right will create a cylinder with an outer radius of 1300 mm and thickness of 100 mm. Note that the material name "steel" is arbitrary and only benefits the user, the material properties will be set later based on built in material profiles. Also of importance is the Data storage level option. This option has importance for both the model analysis and if the user wishes to create shapes through the (boolean) addition and subtraction of OPERA bodies. As quoted in the Reference Manual "When merging bodies with boolean operations, the resulting cells will normally be formed from a combination of the initial cells. In such a case it is not clear which of the initial data sets should be kept with each newly formed cell. The data storage level is used to resolve this conflict, and the data set with the highest storage level is kept. Where the data level is the same, the result is ambiguous and the data is formed by merging the possible data sets." We will require the Data storage level only because of our analysis. Upon clicking "OK", users should find a bright green cylinder around their magnet.

OPERA models require the creation of "meshes", which are surfaces and volumes that are comprised of points connected by lines. As the user creates more regions for meshing ("extra" volumes) the models can be made more accurate. It is of particular importance to put the current source, in our case the solenoid, in a volume of air all by itself. We can then specify the type of material in the volume in order to help the analysis produce more accurate results. Because of the simplicity of this model, we will only need one extra volume, which is the air volume around the magnet. to begin we will, as before we must click in the top menu of the Modeler window Create > Object > Cylinder/Cone.

 As shown in the image to the left, we will be creating a tube of air around the magnet. Note that the dimensions are large enough to ensure that the magnet data volume is completely enclosed by the air volume. Also, our higher Data storage level will allow us to preserve the data within the conductor volume when we create the model body later.

The user may wish to make certain materials translucent so that all of the bodies in the model may be seen with ease. This can be accomplished through the following procedure. Find the command View > Change Colours... in the top menu, then scroll down until under the "Selection" column the "Material' option may be seen. Click on the icon to the left of Material, then select Air and finally click the "Translucency" button at the bottom of the Change Colours window. Users should see the word "Translucent" next to the "Air" label. Next we will create the "background" volume, which will enclose the volume we wish to analyze as well as allow us to specify boundary conditions.

 The "block" body is accessed by clicking Create > Object > Block in the top menu of the Modeler window. Note that the name is specified as "background", this name is unique in OPERA as it sets the body with that name to become the analysis volume. Again, note the Data storage level is set to 2, the same is the yoke and lower than the "magAir" extra volume. Our choice for the background is the forward half of the design. Since our design is symmetric in several axes and we will place our interaction point at (0, 0, 0), we will only compute half the model to save time and file size.

In the next section, the bodies created will be manipulated so surface and volume meshing may be completed and the analysis can begin.

#### Cell Properties and the Model Body

Some of the bodies generated will need further manipulation. For instance, the volume created around the magnet must have its "potential type" altered before the creation of the model body. This will allow the compiler to accurately depict the effects of the enclosed magnet. From the top menu bar of the Modeler window, find the command Picking > Pick Bodies. Now, position the cursor over the air volume "magAir" and double-click, the body should turn a shade of yellow-orange (if the user cannot select the volume then try clicking anywhere around the model and, while holding the mouse button down, rotate the entire model until the "magAir" volume is accessible then release the mouse button). Now, in the top menu find Properties > Cell Properties.... In the window that opens, find the drop down menu for Potential type and select "Reduced", then click "OK" to accept and apply the changes. From the OPERA Reference Manual "The "Reduced" potential type must be used in regions where source currents are flowing." This is why the solenoid is enclosed in a small volume of air, so that we may properly define the volume surrounding the magnet without altering the later results of the model analysis.

 In addition, the user must also define boundary conditions for the magnetic field so that the analysis provides results with physical accuracy. To do this the user will define one face of the "background" volume. Since the user is selecting a face and not an entire body they need to choose Picking > Pick Faces from the top menu of the modeler. Now, double-click the face of the background which intersects all of the other volumes, as shown in the image to the left. Once this has been done, find in the top menu Properties > Face Properties.... The user may now choose an arbitrary Boundary condition label for the face in the in the window that opens. It is recommended that the label used be "nm", to suggest that the boundary condition here is that the magnetic field is normal to the surface (as one would expect with the solenoid). It is also important to set the Data storage level to 2 so that the face properties will be retained during in the model body construction.

The proper analysis type must be selected for the current project. All analysis to date have been for magnetostatic models using OPERA's built in TOSCA algorithm. To ensure the user is running this analysis, please select from the top menu Model > Analysis Type. While hovering the mouse over this submenu, one should note that TOSCA Magnetic should be selected.

 The settings for the TOSCA type analysis may be selected from Model > TOSCA Magnetostatics Settings.... As noted to the left, the Material Properties option should be set to "nonlinear" because of our steel yokes, and Automatic Potential Cuts should also be selected. The Automatic Potential Cuts are small planes that OPERA will add in order to increase the number of meshed regions created. Users can add their own potential cuts manually by creating small planes of air in model bodies. The number of iterations has a default of 21. In most cases the analysis will find solutions which are everywhere smooth in less than 21 iterations. Once solutions are found to match the analysis will finish automatically. Therefore, it is recommended to keep the number of iterations at 21 to allow the modeler enough attempts to finish the analysis within the default Convergence tolerance.
 The boundary conditions may be set at by selecting Model > Set Boundary Conditions... in the top menu. Selecting the "nm" label entered earlier, the user will find the options to the right selectable. By choosing the name earlier carefully, its easy to remember this boundary condition was "normal magnetic" and the correspondong option should be chosen. Then "Apply" should be selected, followed to "OK" to implement the conditions.

Some of the final steps before the creation of the model body involve setting the properties of the materials used in the model.

 The yoke material "steel" must now be defined. Air is built into OPERA so no properties need to be set, but for other we must define their BH Curve. The first of two steps requires that we label each material's BH curve. This is done by opening the Set TOSCA Magnetic Material Properties window through Model > Set Material Properties.... In the window, we select each material and then assign it a BH label. For steel, we should select the "Nonlinear" radio button and choose a label "tenten" (his will be relevant in step two).
 In this second step to setting material properties, the user must select Model > Set BH Curve Properties... from the top modeler menu. On this window, the material types "Default" and "tenten" will be listed. OPERA has a database of BH curves for various materials, from which the user will use the tenten.bh curve for 1010 steel. In order to do this, the user must select the "tenten" label and then select Edit. In the new window that appears locate from the top menu File > Import. The .bh files are located in /afs/rhic.bnl.gov/eic/PACKAGES/OPERA_14R1/bh. Within this folder, the user will find the necessary file. After selecting this file and then selecting Open, the user will find a screen which contains a plot of the BH values. The user may convert these CGS values to SI now in the options menu, although the analysis will convert to SI units automatically (under the conditions specified herein). The user should then choose File > Close to implement these changes and then on the final window select "Close" to finalize the data.
 The final step is to run the analysis. Users may define the resolution of analysis, but the values listed herein are chosen to limit CPU time and produce an effective model for particle simulations. The user must first create the model body by selecting Model > Create Model Body. This will cause any non-conductor material outside of the "background" volume to vanish. Users will notice that if they are in the "Select Body" mode that the entire model now becomes highlighted, indicating the model body is in effect. Once this is done the user can perform one action to complete three: creation of the analysis database and the surface and volume meshes. Selecting Model > Create Analysis Database... will open the window seen in the image to the left. Here, the user will set various parameters. The recommended settings for the SS model are as follows; For Database parameters: model name is "SS-simpleYoke" (the .op3 will be added by default), units are "SI with mm", element type is "Mixed" and surface element type is "Curved". For the surface mesh: the maximum mesh element size should be 250, maximum angle is 10, maximum deviation from surface is 0.1, absolute tolerance for coincidence is 1.0E-06, mesh type is "prefer tetrahedral". For the volume mesh: absolute tolerance for coincidence is 1.0E-06. These values are summarized in the image to the left. The database comments are unnecessary but allow for good record keeping. Also, the save location in the image is unique to R. Darienzo. Any file saved will be saved in the user's eic+u directory. Selecting "Prepare and Solve" from the bottom of the window will begin the analysis process.

Once the analysis finishes a small window will appear reporting that the analysis is finished. Selecting "OK" on this window will reveal the original analysis window and one of the selections will be to "Post-Process". Selecting this will open the analyzed file in the Post-Processor.

### OPERA Post-Processor

Opening a project in the post-processor from the opera manager window can be done by selecting Opera-3d > Post Processor from the "Opera Manager" window. In order to open a project, the user must select File > Open (Activate+Load)... from the top menu of the post-processor. This will automatically adjust the units and load the analyzed file, which has a .op3 extension. On occasion, files are too large to load on the first try. This can be solved by selecting View > Default Select and Refresh. Once the user sees the model then the project has loaded correctly. The only parts of the project which load are the conductors and the bodies which were contained in the model body. It is possible, as per the user manual, to create reflections of the model body, but since all the models studied thus far have had at least one plane of symmetry, this has been unnecessary. As a recommendation, the post-processor will run faster if the x- y- z-axis are removed. This may be accomplished by selecting View > Parts of the Display > Axes. What follows below are several actions which may be performed in the post-processor which are essential to understanding the efficacy of a design. In particular, the rudimentary particle trajectory simulations available in OPERA may be used in conjunction with a program called mapper3.py (created by T. Burton, R. Darienzo). This python program allows multiple particle trajectories to be graphed at the same time so model comparison may be done exactly.

 Perhaps the most useful tool in the post-processor is the magnetic field mapper. Fields can be shown in color on cartesian planes, displayed on spheres and circular planes. The straight line plot is the most ubiquitous, as it can quickly give the user an understanding of how much field equipment will experience and what the field profile looks like over some span in an axis or along the radial direction. The image to the left may be produced by entering the information here. Aside from the field modulus (bmod) users may also plot the radial field (br), and individual components of the field from x, y, or z directions (bx, by, bz).
 Another powerful tool is the field map function. Users may map magnetic fields on a plane, cylinder or sphere. This cn help visualize the location of magnetic "hot spots" on the conductor surface without having to make multiple straight line plots. Users may produce a map of the magnetic field modulus on the yz-plane (shown left) by selecting View > Fields on a Cartesian Patch... and entering the information shown here. The image to the left also employs a "cut plane" which allows users to see inside of a design without hiding the design. The cut plane here was created by first orienting the model though View > Views > From -X then by selecting View > Cut Plane... and choosing the options listed here.

The post-processor's greatest strength is the fact that any conductor may be opened in the post-processor for analysis. This can save time in design development since examining a conductor in the post-processor will take far less time than meshing a model and performing a full analysis. The field profiles obtained by using the post-processor are valid for magnets in air and is in no way un-physical, thus it is strongly recommended that new designs be checked and fine tuned by utilizing both the modeler and post-processor before any serious designing is performed (meshing, material BH curves, etc.).

Before opening any conductor files (.cond or .COND) in the post-processor, the system of units must be defined and should be consistent with the final intended units for the design. The units may be set by selecting File > Commands In... in the post-processor. The file needed for [mm, Tesla, Joules...] is SetPostProcUnits-1.comi (see OPERA Files). If the user has not imported this file, the units may be set manually via Options > Units..., then selecting the appropriate units, followed by "Apply" and then "OK".***

#### Particle Trajectories

 Perhaps the most useful tool in the post-processor is the ability to perform simple simulations of particle trajectories. Shown to the left is the trajectory of a 500 MeV electron with an initial angle of 2° to the z-axis in the ZX plane, with the user looking down the z-axis toward the origin (IP). Higher level simulations should be performed using eicROOT. The OPERA trajectories should be used to help understand whether or not a design should be pursued and not for example, making studies into the momentum resolution afforded by a design. While a design is opened, users may perform their own particle trajectory simulations by selecting Trajectories > Calculate Particle Trajectories.... In the window that opens, users will be able to set the beam energy through the "Accelerating voltage" and the charge species trough "Particle type". Currently, "Step length" is 0.1 and the "Number of steps" is set to end on the boundary of the analysis region. In the image to the left, the 2° initial direction was accomplished through the Trajectory Start tab of the window. Under "Direction" select "Parallel to". By choosing "Other" the fields below are made selectable, allowing us to enter "2" in the "Around new Y" field. This means that the particle is fired along the z-axis, which has now been rotated towards the x-axis by 2°. It is recommended that the file name should be made to be very descriptive, including beam energy, design name and angle, for example n_SS_3T_5GeV_2deg.tracks. The files created will be stored in the users main directory with the extension .tracks.

As mentioned above, OPERA can perform simple particle trajectory simulations. The output file and built-in analysis functions to not allow for multiple trajectories to be viewed simultaneously, nor does it allow for cross-hairs for accurate determination of the actual particle coordinates. This motivated the BNL EIC task force to develop a simple python program to stitch together two (or more, depending on any simple additions to the code) OPERA .tracks files. The program still requires some careful preparation in order to extract the relevant data from OPERA. Once the .tracks files are created, the user must open two new post-processor windows. In each of these windows, the user must set the units by selecting File > Commands In... and then choosing SetPostProcUnits-1.comi. Once set, the user must then open the previously created particle trajectories via Trajectories > Graph Trajectories.... In the window that opens, the user must choose their .tracks file and be sure to select the option "Print to lp file". It is recommended that users wait to select "Display" until an identifiable time. This is important because the .lp files are listed with a long and difficult to read file name. For this reason, file names used with mapper3 are chosen based on their timestamp, as shown through the command ls -l *.lp. Once the user has made all of the particle trajectory files desired, they will then locate them in the opera_logs/ directory using ls -l *.lp. The mapper program is then invoked by typing

./mapper3.py filename_1.lp filename_2.lp

This will produce a .png file, and will automatically name the files based on the original particle trajectory filenames, hence the need to create specific particle trajectory file names. The user may view the map file with

display mapper_filename.png

The .png file created has a large resolution, and may have issues loading. The large resolution was chosen because the images have always been sent to the user's desktop before being uploaded to the wiki or put in a presentation. The images, as viewed on the user's desktop, are much smaller than their native resolutions. Thus is was necessary to increase resolution in order to keep the images clear and readable. If a smaller resolution is desired, it may be changed in the mapper3.py program script.

### OPERA Files

Post-Processor Set Units File

The file SetPostProcUnits-1.comi for setting the units in the post-processor (in lieu of opening an analyzed .op3 file) should be created in the user's home directory. It should contain the line

UNITS LENG=MM FLUX=TESLA FIEL=AM SCAL=AMP VECT=WBM DISP=CM2 ELEC=VM COND=SM CURD=AMM2 POWE=WATT FORC=NEWTON ENER=JOULE MASS=KG

The file should then be saved as SetPostProcUnits-1.comi, such that when it is mentioned in the above tutorial it may be located easily.

Particle Trajectory Mapper

The program mapper3.py is located here.