# Starfish Tutorial Part 1: Domain, Boundaries, and a Potential Solver

Posted on October 29th, 2012
Previous Article :: Next Article

## Starfish Tutorial

Over the past few months, we at Particle In Cell Consulting have been busy developing a generalized two-dimensional particle in cell (2D PIC) simulation code called Starfish. We are getting close to releasing the code to the public. It will be released in two “flavors”. The first, a light version will be available for free, and will contain the basic functionality needed to investigate plasma and rarefied gas flows in academic setting. The full version will contain advanced particle injection and material interaction models for use in actual industrial applications. Starfish will eventually contain a GUI that will simplify setting up and analyzing the cases. However, for now, the code consists solely of an input-file driven solver. In this tutorial we will guide you through the steps used to setup a representative simulation. In the simulation we will investigate the flow of plasma over a charged cylinder, and will consider erosion of the cylinder due to ion bombardment. In this first lesson, we will go through the steps needed to specify the computational domain, add the geometry (the cylinder), solve the potential, and output the results.

## Running Starfish

Starfish is a Java application and in order to run it, you will need to have the Java run time environment installed. You will also need the input files, which you can download here: step1.zip.

It is possible that your machine already associates jar files with Java. If it does not, see this good article on how to make jar files launch by double clicking. Alternatively, you can launch the solver from the command line. Use your operating system specific instructions to unzip the tutorial input files and then navigate to the folder. For instance, on Microsoft Windows 7, you would go to the Start menu, type cmd into the search field, and press enter to launch the command prompt. Then once you navigate into the folder with the cd command, you would type in java -jar starfish.jar to launch the code. If everything went well, you will see:

C:\codes\starfish\dat\tutorial\step1>java -jar starfish.jar
================================================================
> Starfish 0.1 (Devel)
> General 2D PIC+DSMC Code
> Development team: L. Brieda, A. Barrie, M. Keidar
> (c) 2012, Particle In Cell Consulting LLC, particleincell.com
=================================================================

Processing <note>
**Starfish Tutorial: Part 1**
Processing <domain>
Processing <materials>
Processing <boundaries>
Processing <solver>
Processing <time>
Processing <starfish>
Starting main loop
it: 0   O2+: 0
WARNING:  !! GS failed to converge in 10000 iteration, norm = 1.3797628795224026
WARNING:  !! GS failed to converge in 10000 iteration, norm = 0.004582671221260977
WARNING:  !! GS failed to converge in 10000 iteration, norm = 6.91735940453368E-6
Processing <output>
Processing <output>
Processing <output>
Done!

You will also see few new files: boundaries.dat, mesh.dat, and profile.dat. These files contain various simulation outputs in a simple Tecplot format. Plots made from these files can be seen below in Figure 1. In addition, you will also find a log file starfish.log which contains some additional details.

## Starfish Input File (starfish.xml)

When Starfish is launched as in the example above, it looks in the current directory for a file named starfish.xml. This file contains all the commands that drive the simulation. The file used to produce the output in Figure 1 is shown below:

1. <simulation>
2. <note>Starfish Tutorial: Part 1</note>
3. 
4. <!-- load input files -->
5. <load>domain.xml</load>
6. <load>materials.xml</load>
7. <load>cylinder.xml</load>
8. 
9. <!-- set potential solver -->
10. <solver type="poisson">
11. <n0>1e12</n0>
12. <Te0>1.5</Te0>
13. <phi0>0</phi0>
14. <max_it>1e4</max_it>
15. </solver>
16. 
17. <!-- set time parameters -->
18. <time>
19. <num_it>1</num_it>
20. <dt>1e-6</dt>
21. </time>
22. 
23. <!-- run simulation -->
24. <starfish />
25. 
26. <!-- save results -->
27. <output type="2D" file_name="field.dat" format="tecplot">
28. <variables>phi, rho, nd.O+</variables>
29. </output>
30. 
31. <output type="1D" file_name="profile.dat" format="tecplot">
32. <mesh>mesh1</mesh>
33. <index>J=0</index>
34. <variables>phi, rho, nd.o+</variables>
35. </output>
36. 
37. <output type="boundaries" file_name="boundaries.dat" format="tecplot" />
38. 
39. </simulation>

As you can see, this file is an XML document and it contains a number of elements nested within the parent <simulation> element. Each XML element consists of a closing and an end tag, as in:

<starfish>
...
</starfish>

These can however be collapsed to a single line, which is especially handy for simpler commands:

<starfish />

XML documents can also contain comments:

<!-- this is a comment -->

Each element can contain children and/or attributes. Starfish does not distinguish between child nodes and attributes and it’s totally up to you, the end user, to use the way that works best for you. For instance, the commands below are identical:

<!-- output with child nodes -->
<output>
<type>2D</type>
<file_name>field.dat</file_name>
<format>tecplot</format>
<variables>phi, rho, nd.O+</variables>
</output>

<!-- the same output command with a mix of child nodes and attributes -->
<output type="2D" file_name="field.dat" format="tecplot">
<variables>phi, rho, nd.O+</variables>
</output>

<!-- the same output specified using only attributes -->
<output type="2D" file_name="field.dat" format="tecplot" variables="phi, rho, nd.O+" />

## Line-by-Line Command Listing

### Line 2: <note>

The input file starts with the note command, which simply outputs the specified message to the screen and the log file. This is a convenient way to remind you what simulation case the code is running.

The file next contains three load commands. These commands load the specified file and place it into the XML tree at the current position. They are used to split a single input file into more manageable smaller chunks. This command is particularly handy for data reuse, for instance, to reuse commonly used material definitions and material interaction tables. Here at PIC-C we typically split the input such that domain, boundary, materials, and material interactions are in separate files. We will go through the content of these in more detail below.

### Lines 10-15: <solver>

Lines 10 through 15 contain the solver command. This command is used to specify the details of the solver that will be used in the simulation. A number of solvers exist (and are discussed in more detail in the user’s guide), but here we use the non-linear Poisson solver. The parameters specify the reference values for the Boltzmann electron model, as well as the maximum number of iterations for the linear solver. Other parameters can also be set, such as the tolerance, and the settings for the non-linear NR solver, but here we just use the defaults. You can see the value of these by looking in the log file.

### Lines 18-21: <time>

We next set time control parameters. We tell the code to run for a total of zero iterations. We also specify the time step size, which in this case is not needed. Running for zero iterations instructs the code to solve the initial field, but it will not attempt to inject particles (assuming sources were defined).

### Line 24: <starfish>

On line 24 we finally start the simulation with the starfish command. All commands before this one were simply specifying the inputs, now these are used to compute the solution. The input file parser will wait for the solver to finish before moving to the next command.

### Lines 27-37: <output>

By itself, the starfish command does not produce any useful output. The computed results are stored internally in memory data structures and must be saved to the output file. This is done with the output command. Three types of output are supported: 2D, 1D, and Boundaries. The first saves data on the 2D computational mesh. The 1D type is similar but it saves only a subset of the mesh, one with a fixed I or J coordinate. The Boundaries output saves data along the simulation geometry. This plot is useful for outputting surface-type parameters such as erosion rate or surface flux. Here we use it to simply save the loaded object geometry.

## Domain File (domain.xml)

We now return to line 5, and consider the domain specification. The domain file, domain.xml, contains the following:

<domain type="xy">

<mesh type="uniform" name="mesh1">
<origin>-0.15,0</origin>
<spacing>5e-3, 5e-3</spacing>
<nodes>70, 40</nodes>
<mesh-bc wall="left" type="dirichlet" value="0" />
</mesh>

</domain>

One of the unique features of Starfish is its ability to load an arbitrary number of computational meshes. These meshes can be either rectilinear or body fitted elliptic meshes. In this example, we specify just a single rectilinear mesh. However, we first tell the code that our geometry is in the Cartesian (XY) coordinate system. Starfish also supports axisymmetric (RZ) domains. The uniform Cartesian mesh is specified by providing the location of the origin, node spacing, and the number of nodes in the two coordinate directions. We also apply a mesh boundary condition by setting the left wall to a fixed 0V potential. This is needed in order to create a potential gradient between the ambient free space and the sphere.

## Materials definition (materials.xml)

Starfish does not contain any build database of materials or material interactions. This information must be provided by the user. Since we don’t have any particles in this first step, we don’t yet concern ourselves with the interactions, however, we need to define the materials that will be present in the simulation. The materials file contains the following:

<!-- materials file -->
<materials>

<material name="O+" type="kinetic">
<molwt>16</molwt>
<charge>1</charge>
<spwt>5e9</spwt>
<init>nd_back=1e4</init>
</material>

<material name="SS" type="solid">
<molwt>52.3</molwt>
<density>8000</density>
</material>

</materials>

As you can see, we defined two materials: atomic oxygen ions and stainless steel. The atomic oxygen ions are kinetic. This material will be modeled with simulation particles within the particle in cell method. Starfish also supports fluid materials, which use Navier Stokes or MHD equations to propagate densities, as well as solid materials, which don’t change throughout the simulation. The parameters needed to specify a material will depend greatly on the type of the material. For the kinetic oxygen ions, we specify the particle specific weight, or the number of real particles each simulation macroparticle represents. This number will influence the number of simulation particles in the simulation. We also specify the background density. A non-zero background density is required whenever the Boltzmann electron model is used due to the presence of the logarithmic term.

## Geometry file (cylinder.xml)

The final piece is the geometry file cylinder.xml, which is listed below:

<boundaries>

<boundary name="cylinder" type="solid" value="-100">
<material>SS</material>
<path>M 0.0500000,0.00000 L 0.0475528,0.0154508 0.0404508,0.0293893 0.0293893,0.0404508
0.0154508,0.0475528 3.06162e-18,0.0500000 -0.0154508,0.0475528 -0.0293893,0.0404508 -0.0404508,0.0293893
-0.0475528,0.0154508 -0.0500000,6.12323e-18 -0.0475528,-0.0154508 -0.0404508,-0.0293893
-0.0293893,-0.0404508 -0.0154508,-0.0475528 -9.18485e-18,-0.0500000 0.0154508,-0.0475528
0.0293893,-0.0404508 0.0404508,-0.0293893 0.0475528,-0.0154508 0.0500000,-1.22465e-17</path>
</boundary>

</boundaries>

Currently, simulation objects are specified via linear or cubic Bezier splines. It is possible that a future version of the code will include elementary building-block shapes and support for other file formats. The boundary contains a child field called path which provides the geometrical information about the spline. The syntax is similar to the SVG format, with the exception that cubic splines are specified by simply listing the points through which the spline will pass and the control knot points are omitted. Here we use linear components (L) to trace a circle. The ordering of the nodes matters, since the code will use the ordering to figure out which side of the segment is “internal” to the object. The internal side is assumed to lie on the “left”, hence the circle segments move counter-clockwise. This path was created with the included MakeCircle.java program.

### Mesh Generation

Finally, a quick note about mesh generation. Right now, Starfish supports just the “staircase” method. The code simply uses the provided surface boundary to figure out which mesh nodes are internal, and these nodes are given the boundary condition of the surface spline. A more detailed method of using cut cells is still in development. You can see in Figure 2 below the staircasing effect. Zooming in on the circle, we can see which nodes are flagged as internal (red contour) and which are external (blue). The staircasing effect is however not of much concern to the solution, since the Poisson solver will smooth out the irregularities.

Continue to Starfish Tutorial Part 2.

Subscribe to the newsletter and follow us on Twitter. Send us an email if you have any questions.