[[sec_meshConversion]]
=== Mesh conversion

The user can generate meshes using other packages and convert them into the
format that {project} uses. There are numerous mesh conversion utilities listed
in <<tab_standardUtilities>>. Some of the more popular mesh converters are
listed below and their use is presented in this section.


`fluentMeshToFoam`::
  (((`fluentMeshToFoam` utility)))(((utility,`fluentMeshToFoam`))) reads a
  'Fluent' `.msh` mesh file, working for both 2-D and 3-D cases;
`starToFoam` (((`starToFoam` utility)))(((utility,`starToFoam`)))::
  reads 'STAR-CD'/'PROSTAR' mesh files.
`gambitToFoam` (((`gambitToFoam` utility)))(((utility,`gambitToFoam`)))::
  reads a 'GAMBIT' `.neu` neutral file;
`ideasToFoam` (((`ideasToFoam` utility)))(((utility,`ideasToFoam`)))::
reads an 'I-DEAS' mesh written in 'ANSYS' `.ans` format;
`cfx4ToFoam` (((`cfx4ToFoam` utility)))(((utility,`cfx4ToFoam`)))::
  reads a 'CFX' mesh written in `.geo` format;

==== `fluentMeshToFoam`

'Fluent' writes mesh data to a single file with a filename:.msh[] extension.
The file must be written in ASCII format, which is not the default option in
'Fluent'. It is possible to convert single-stream 'Fluent' meshes, including
the 2 dimensional geometries. In {project}, 2 dimensional geometries are
currently treated by defining a mesh in 3 dimensions, where the front and back
plane are defined as the `empty` boundary patch type. When reading a 2
dimensional 'Fluent' mesh, the converter automatically extrudes the mesh in the
third direction and adds the empty patch, naming it `frontAndBackPlanes`.

The following features should also be observed.

- The {project} converter will attempt to capture the 'Fluent' boundary
  condition definition as much as possible; however, since there is no clear,
  direct correspondence between the {project} and 'Fluent' boundary conditions,
  the user should check the boundary conditions before running a case.
- Creation of axi-symmetric meshes from a 2 dimensional mesh is currently not
  supported but can be implemented on request.
- Multiple material meshes are not permitted. If multiple fluid materials
  exist, they will be converted into a single {project} mesh; if a solid region
  is detected, the converter will attempt to filter it out.
- 'Fluent' allows the user to define a patch which is internal to the mesh,
  'i.e.' consists of the faces with cells on both sides. Such patches are not
  allowed in {project} and the converter will attempt to filter them out.
- There is currently no support for embedded interfaces and refinement trees.

The procedure of converting a 'Fluent' filename:.msh[] file is first to create
a new {project} case by creating the necessary directories/files: the case
directory containing a filename:controlDict[] file in a dirname:system[]
subdirectory. Then at a command prompt the user should execute:

-------------------------------------------------------------------------------
$ freefoam fluentMeshToFoam '<meshFile>'
-------------------------------------------------------------------------------

where `<meshFile>` is the name of the filename:.msh[] file, including the full
or relative path.

==== `starToFoam`

This section describes how to convert a mesh generated on the 'STAR-CD' code
into a form that can be read by {project} mesh classes. The mesh can be
generated by any of the packages supplied with 'STAR-CD', 'i.e.' 'PROSTAR',
'SAMM', 'ProAM' and their derivatives. The converter accepts any single-stream
mesh including integral and arbitrary couple matching and all cell types are
supported. The features that the converter does not support are:

- multi-stream mesh specification;
- baffles, 'i.e.' zero-thickness walls inserted into the domain;
- partial boundaries, where an uncovered part of a couple match is considered
  to be a boundary face;
- sliding interfaces.

For multi-stream meshes, mesh conversion can be achieved by writing each
individual stream as a separate mesh and reassemble them in {project}.

{project} adopts a policy of only accepting input meshes that conform to the
fairly stringent validity criteria specified in <<sec_blockMeshDict>>. It will
simply not run using invalid meshes and cannot convert a mesh that is itself
invalid. The following sections describe steps that must be taken when
generating a mesh using a mesh generating package supplied with 'STAR-CD' to
ensure that it can be converted to {project} format. To avoid repetition in the
remainder of the section, the mesh generation tools supplied with 'STAR-CD'
will be referred to by the collective name 'STAR-CD'.

===== General advice on conversion

We strongly recommend that the user run the 'STAR-CD' mesh checking tools
before attempting a `starToFoam` conversion and, after conversion, the
`checkMesh`(((`checkMesh` utility)))(((utility,`checkMesh`))) utility should be
run on the newly converted mesh. Alternatively, `starToFoam` may itself issue
warnings containing 'PROSTAR' commands that will enable the user to take a
closer look at cells with problems.  Problematic cells and matches should be
checked and fixed before attempting to use the mesh with {project}. Remember
that an invalid mesh will not run with {project}, but it may run in another
environment that does not impose the validity criteria.

Some problems of tolerance matching can be overcome by the use of a matching
tolerance in the converter. However, there is a limit to its effectiveness and
an apparent need to increase the matching tolerance from its default level
indicates that the original mesh suffers from inaccuracies.

===== Eliminating extraneous data

When mesh generation in is completed, remove any extraneous vertices and
compress the cells boundary and vertex numbering, assuming that fluid cells
have been created and all other cells are discarded. This is done with the
following 'PROSTAR' commands:


-------------------------------------------------------------------------------
CSET NEWS FLUID
CSET INVE
-------------------------------------------------------------------------------

The `CSET` should be empty. If this is not the case, examine the cells in
`CSET` and adjust the model. If the cells are genuinely not desired, they can
be removed using the 'PROSTAR' command:

-------------------------------------------------------------------------------
CDEL CSET
-------------------------------------------------------------------------------

Similarly, vertices will need to be discarded as well:

-------------------------------------------------------------------------------
CSET NEWS FLUID
VSET NEWS CSET
VSET INVE
-------------------------------------------------------------------------------

Before discarding these unwanted vertices, the unwanted boundary faces have to
be collected before purging:

-------------------------------------------------------------------------------
CSET NEWS FLUID
VSET NEWS CSET
BSET NEWS VSET ALL
BSET INVE
-------------------------------------------------------------------------------

If the `BSET` is not empty, the unwanted boundary faces can be deleted using:

-------------------------------------------------------------------------------
BDEL BSET
-------------------------------------------------------------------------------

At this time, the model should contain only the fluid cells and the supporting
vertices, as well as the defined boundary faces. All boundary faces should be
fully supported by the vertices of the cells, if this is not the case, carry on
cleaning the geometry until everything is clean.

===== Removing default boundary conditions

By default, 'STAR-CD' assigns wall boundaries to any boundary faces not
explicitly associated with a boundary region. The remaining boundary faces are
collected into a `default` boundary region, with the assigned boundary type
`0`. {project} deliberately does not have a concept of a `default` boundary
condition for undefined boundary faces since it invites human error, 'e.g.'
there is no means of checking that we meant to give all the unassociated faces
the default condition.

Therefore *all* boundaries for each {project} mesh must be specified for a mesh
to be successfully converted. The `default` boundary needs to be transformed
into a real one using the procedure described below:

. Plot the geometry with `Wire Surface` option
. Define an extra boundary region with the same parameters as the `default`
  region 0 and add all visible faces into the new region, say 10, by selecting
  a zone option in the boundary tool and drawing a polygon around the entire
  screen draw of the model. This can be done by issuing the following commands
  in 'PROSTAR':
+
-------------------------------------------------------------------------------
RDEF 10 WALL
BZON 10 ALL
-------------------------------------------------------------------------------
+
. We shall remove all previously defined boundary types from the set. Go
  through the boundary regions:
+
-------------------------------------------------------------------------------
BSET NEWS REGI 1
BSET NEWS REGI 2
... 3, 4, ...
-------------------------------------------------------------------------------
+
Collect the vertices associated with the boundary set and then the boundary
faces associated with the vertices (there will be twice as many of them as in
the original set).
+
-------------------------------------------------------------------------------
BSET NEWS REGI 1
VSET NEWS BSET
BSET NEWS VSET ALL
BSET DELE REGI 1
REPL
-------------------------------------------------------------------------------
+
This should give the faces of boundary Region 10 which have been defined on top
of boundary Region 1. Delete them with `BDEL BSET`. Repeat these for all
regions.

===== Renumbering the model

Renumber and check the model using the commands:

-------------------------------------------------------------------------------
CSET NEW FLUID
CCOM CSET

VSET NEWS CSET
VSET INVE (Should be empty!)
VSET INVE
VCOM VSET

BSET NEWS VSET ALL
BSET INVE (Should be empty also!)
BSET INVE
BCOM BSET

CHECK ALL
GEOM
-------------------------------------------------------------------------------

Internal 'PROSTAR' checking is performed by the last two commands, which may
reveal some other unforeseeable error(s). Also, take note of the scaling factor
because 'PROSTAR' only applies the factor for 'STAR-CD' and not the geometry.
If the factor is not 1, use the `scalePoints`(((`scalePoints` utility)))
(((utility,`scalePoints`))) utility in {project}.

===== Writing out the mesh data

Once the mesh is completed, place all the integral matches of the model into
the couple type 1. All other types will be used to indicate arbitrary matches.

-------------------------------------------------------------------------------
CPSET NEWS TYPE INTEGRAL
CPMOD CPSET 1
-------------------------------------------------------------------------------

The components of the computational grid must then be written to their own
files. This is done using 'PROSTAR' for boundaries by issuing the command

-------------------------------------------------------------------------------
BWRITE
-------------------------------------------------------------------------------

by default, this writes to a filename:.23[] file (versions prior to 3.0) or a
filename:.bnd[] file (versions 3.0 and higher). For cells, the command

-------------------------------------------------------------------------------
CWRITE
-------------------------------------------------------------------------------

outputs the cells to a filename:.14[] or filename:.cel[] file and for vertices,
the command

-------------------------------------------------------------------------------
VWRITE
-------------------------------------------------------------------------------

outputs to file a filename:.15[] or filename:.vrt[] file. The current default
setting writes the files in ASCII format. If couples are present, an additional
couple file with the extension filename:.cpl[] needs to be written out by
typing:

-------------------------------------------------------------------------------
CPWRITE
-------------------------------------------------------------------------------

After outputting to the three files, exit 'PROSTAR' or close the files. Look
through the panels and take note of all 'STAR-CD' sub-models, material and
fluid properties used &ndash; the material properties and mathematical model
will need to be set up by creating and editing {project} dictionary files.

The procedure of converting the 'PROSTAR' files is first to create a new
{project} case by creating the necessary directories. The 'PROSTAR' files must
be stored within the same directory and the user must change the file
extensions: from filename:.23[], filename:.14[] and filename:.15[] (below
'STAR-CD' version 3.0), or filename:.pcs[], filename:.cls[] and filename:.vtx[]
('STAR-CD' version 3.0 and above); to filename:.bnd[], filename:.cel[] and
filename:.vrt[] respectively.

===== Converting the mesh to {project} format

The translator utility `starToFoam` can now be run to create the boundaries,
cells and points files necessary for a {project} run:

-------------------------------------------------------------------------------
$ freefoam starToFoam '<meshFilePrefix>'
-------------------------------------------------------------------------------

where '<meshFilePrefix>' is the name of the the prefix of the mesh files,
including the full or relative path. After the utility has finished running,
{project} boundary types should be specified by editing the filename:boundary[]
file by hand.

==== `gambitToFoam`

'GAMBIT' writes mesh data to a single file with a filename:.neu[] extension.
The procedure of converting a 'GAMBIT' filename:.neu[] file is first to create
a new {project} case, then at a command prompt, the user should execute:

-------------------------------------------------------------------------------
$ freefoam gambitToFoam '<meshFile>'
-------------------------------------------------------------------------------

where `<meshFile>` is the name of the filename:.neu[] file, including the full
or relative path.  The 'GAMBIT' file format does not provide information about
type of the boundary patch, 'e.g.' wall, symmetry plane, cyclic. Therefore all
the patches have been created as type patch.  Please reset after mesh
conversion as necessary.

==== `ideasToFoam`

{project} can convert a mesh generated by 'I-DEAS' but written out in 'ANSYS'
format as a filename:.ans[] file. The procedure of converting the
filename:.ans[] file is first to create a new {project} case, then at a command
prompt, the user should execute:

-------------------------------------------------------------------------------
$ freefoam ideasToFoam '<meshFile>'
-------------------------------------------------------------------------------

where `<meshFile>` is the name of the filename:.ans[] file, including the full
or relative path.

==== `cfx4ToFoam`

'CFX' writes mesh data to a single file with a filename:.geo[] extension. The
mesh format in 'CFX' is block-structured, 'i.e.' the mesh is specified as a set
of blocks with glueing information and the vertex locations. {project} will
convert the mesh and capture the 'CFX' boundary condition as best as possible.
The 3 dimensional `patch' definition in 'CFX', containing information about the
porous, solid regions 'etc.' is ignored with all regions being converted into a
single {project} mesh. 'CFX' supports the concept of a `default' patch, where
each external face without a defined boundary condition is treated as a `wall`.
These faces are collected by the converter and put into a +defaultFaces+ patch
in the {project} mesh and given the type +wall+; of course, the patch type can
be subsequently changed.

Like, {project} 2 dimensional geometries in 'CFX' are created as 3 dimensional
meshes of 1 cell thickness. If a user wishes to run a 2 dimensional case on a
mesh created by 'CFX', the boundary condition on the front and back planes
should be set to `empty`; the user should ensure that the boundary conditions
on all other faces in the plane of the calculation are set correctly. Currently
there is no facility for creating an axi-symmetric geometry from a 2
dimensional 'CFX' mesh.

The procedure of converting a 'CFX' filename:.geo[] file is first to create a
new {project} case, then at a command prompt, the user should execute:

-------------------------------------------------------------------------------
$ freefoam cfx4ToFoam '<meshFile>'
-------------------------------------------------------------------------------

where `<meshFile>` is the name of the filename:.geo[] file, including the full
or relative path.
