README.md 9.25 KB
Newer Older
Mark Olesen's avatar
Mark Olesen committed
1
## About OpenFOAM
Mark Olesen's avatar
Mark Olesen committed
2
3
4
5
OpenFOAM is a free, open source CFD software [released and developed by OpenCFD Ltd since 2004](http://www.openfoam.com/history/).
It has a large user base across most areas of engineering and science, from both commercial and academic organisations.
OpenFOAM has an extensive range of features to solve anything from complex fluid flows involving chemical reactions, turbulence and heat transfer, to acoustics, solid mechanics and electromagnetics.
[See documentation](http://www.openfoam.com/documentation)
Fred Mendonca's avatar
Fred Mendonca committed
6

7
8
OpenFOAM is professionally released every six months to include
customer sponsored developments and contributions from the community -
Mark Olesen's avatar
Mark Olesen committed
9
10
11
individual and group contributors, integrations
(eg, from FOAM-extend and OpenFOAM Foundation Ltd) as well as
[governance guided activities](https://www.openfoam.com/governance/).
Andrew Heather's avatar
Andrew Heather committed
12
13


14
## License
15
16
17
18
19
20
21
22

OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.  See the file COPYING in this directory or
[http://www.gnu.org/licenses/](http://www.gnu.org/licenses), for a
description of the GNU General Public License terms under which you
may redistribute files.
Andrew Heather's avatar
Andrew Heather committed
23
24


Mark Olesen's avatar
Mark Olesen committed
25
## OpenFOAM Trademark
Andrew Heather's avatar
Andrew Heather committed
26

27
28
29
OpenCFD Ltd grants use of its OpenFOAM trademark by Third Parties on a
licence basis. ESI Group and OpenFOAM Foundation Ltd are currently
permitted to use the Name and agreed Domain Name. For information on
30
31
trademark use, please refer to the
[trademark policy guidelines][link trademark].
32
33

Please [contact OpenCFD](http://www.openfoam.com/contact) if you have
34
any questions about the use of the OpenFOAM trademark.
Andrew Heather's avatar
Andrew Heather committed
35

36
Violations of the Trademark are monitored, and will be duly prosecuted.
Andrew Heather's avatar
Andrew Heather committed
37
38


Mark Olesen's avatar
Mark Olesen committed
39
## Using OpenFOAM
40
41
42

If OpenFOAM has already been compiled on your system, simply source
the appropriate `etc/bashrc` or `etc/cshrc` file and get started.
43
For example, for the OpenFOAM-v2106 version:
44
```
45
source /installation/path/OpenFOAM-v2106/etc/bashrc
46
47
```

Mark Olesen's avatar
Mark Olesen committed
48
## Compiling OpenFOAM
49

50
51
If you are compiling OpenFOAM from source, please see the relevant
guides:
52
53
54
55
56
57
58

| Location    | Readme    | Requirements | Build |
|-------------|-----------|--------------|-------|
| [OpenFOAM][repo openfoam] | [readme][link openfoam-readme] | [system requirements][link openfoam-require] | [build][link openfoam-build] |
| [ThirdParty][repo third] | [readme][link third-readme] | [system requirements][link third-require] | [build][link third-build] |


59
60
61
62
63
If you need to modify the versions or locations of ThirdParty
software, please read how the
[OpenFOAM configuration][wiki-config] is structured.


Mark Olesen's avatar
Mark Olesen committed
64
## How do I know which version I am currently using?
65
66
67
68
69
70
71

The value of the `$WM_PROJECT_DIR` or even `$WM_PROJECT_VERSION` are
not guaranteed to have any correspondence to the OpenFOAM release
(API) value. If OpenFOAM has already been compiled, the build-time
information is embedded into each application. For example, as
displayed from `blockMesh -help`:
```
72
73
Using: OpenFOAM-com (2012) - visit www.openfoam.com
Build: b830beb5ea-20210429 (patch=210414)
74
75
76
77
Arch:  LSB;label=32;scalar=64
```
This output contains all of the more interesting information that we need:

78
79
| item                  | value         |
|-----------------------|---------------|
80
81
82
83
84
| version               | com  (eg, local development branch) |
| api                   | 2012          |
| commit                | b830beb5ea    |
| author date           | 20210429      |
| patch-level           | (20)210414    |
85
86
87
88
| label/scalar size     | 32/64 bits    |

The Arch information may also include the `solveScalar` size
if different than the `scalar` size.
89
90
91
92
93

As can be seen in this example, the git build information is
supplemented by the date when the last change was authored, which can
be helpful when the repository contains local changes. If you simply
wish to know the current API and patch levels directly, the
94
`wmake -build-info` provides the relevant information even
95
96
when OpenFOAM has not yet been compiled:
```
97
$ wmake -build-info
98
make
99
100
    api = 2012
    patch = 210414
101
    branch = master
102
    build = 308af39136-20210426
103
104
105
106
107
```
Similar information is available with `foamEtcFile`, using the
`-show-api` or `-show-patch` options. For example,
```
$ foamEtcFile -show-api
108
2012
109
110

$ foamEtcFile -show-patch
111
210414
112
113
114
115
116
117
118
```
This output will generally be the easiest to parse for scripts.
The `$FOAM_API` convenience environment variable may not reflect the
patching changes made within the currently active environment and
should be used with caution.


Mark Olesen's avatar
Mark Olesen committed
119
## ThirdParty directory
120
121
122
123
124
125
126
127
128
129

OpenFOAM normally ships with a directory of 3rd-party software and
build scripts for some 3rd-party software that is either necessary or
at least highly useful for OpenFOAM, but which are not necessarily
readily available on every operating system or cluster installation.

These 3rd-party sources are normally located in a directory parallel
to the OpenFOAM directory. For example,
```
/path/parent
130
131
|-- OpenFOAM-v2106
\-- ThirdParty-v2106
132
133
134
135
136
137
138
```
There are, however, many cases where this simple convention is inadequate:

* When no additional 3rd party software is actually required (ie, the
  operating system or cluster installation provides it)

* When we have changed the OpenFOAM directory name to some arbitrary
139
  directory name, e.g. openfoam-sandbox2106, etc..
140
141
142
143
144
145
146
147
148
149
150

* When we would like any additional 3rd party software to be located
  inside of the OpenFOAM directory to ensure that the installation is
  encapsulated within a single directory structure. This can be
  necessary for cluster installations, or may simply be a convenient
  means of performing a software rollout for individual workstations.

* When we have many different OpenFOAM directories for testing or
  developing various different features but wish to use or reuse the
  same 3rd party software for them all.

151
152
The solution for these problems is a newer, more intelligent discovery
when locating the ThirdParty directory with the following precedence:
153
154
155
156
157
158

1. PROJECT/ThirdParty
   * for single-directory installations
2. PREFIX/ThirdParty-VERSION
   * this corresponds to the traditional approach
3. PREFIX/ThirdParty-vAPI
159
   * allows for an updated value of VERSION, *eg*, `v2106-myCustom`,
160
     without requiring a renamed ThirdParty. The API value would still
161
     be `2106` and the original `ThirdParty-v2106/` would be found.
162
4. PREFIX/ThirdParty-API
163
   * same as the previous example, but using an unadorned API value.
164
5. PREFIX/ThirdParty-common
165
166
   * permits maximum reuse for various versions, for experienced
     users who are aware of potential version incompatibilities
167

168
169
170
171
172
If none of these directories are found to be suitable, it reverts to
using PROJECT/ThirdParty as a dummy location (even if the directory
does not exist). This is a safe fallback value since it is within the
OpenFOAM directory structure and can be trusted to have no negative
side-effects. In the above, the following notation has been used:
173
174
175
176
177
178

| name          | value         | meaning       |
|---------------|---------------|---------------|
| PROJECT       | `$WM_PROJECT_DIR`     | The OpenFOAM directory |
| PREFIX        | `dirname $WM_PROJECT_DIR` | The OpenFOAM parent directory |
| API           | `foamEtcFiles -show-api` |  The api or release version |
179
| VERSION       | `$WM_PROJECT_VERSION` | The version we have chosen |
180
181
182
183
184
185
186

To reduce the potential of false positive matches (perhaps some other
software also uses ThirdParty-xxx for its naming), the directory test
is accompanied by a OpenFOAM-specific sanity test. The OpenFOAM
ThirdParty directory will contain either an `Allwmake` file or a
`platforms/` directory.

187
188
189

<!-- OpenFOAM -->

190
191
[link trademark]: https://www.openfoam.com/opencfd-limited-trade-mark-policy

Mark Olesen's avatar
Mark Olesen committed
192
193
[repo openfoam]: https://develop.openfoam.com/Development/openfoam/
[repo third]: https://develop.openfoam.com/Development/ThirdParty-common/
194

Mark Olesen's avatar
Mark Olesen committed
195
196
197
198
199
200
201
[link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md
[link openfoam-issues]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/BuildIssues.md
[link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md
[link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md
[link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md
202

203
204
[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring

205

Mark Olesen's avatar
Mark Olesen committed
206
## Useful Links
207

208
- Download [source](https://dl.openfoam.com/source/) and [download and installation instructions](http://www.openfoam.com/download/)
Andrew Heather's avatar
Andrew Heather committed
209
- [Documentation](http://www.openfoam.com/documentation)
Andrew Heather's avatar
Andrew Heather committed
210
- [Reporting bugs/issues/feature requests](http://www.openfoam.com/code/bug-reporting.php)
211
- [Issue tracker](https://develop.openfoam.com/Development/openfoam/-/issues)
212
213
- [Code wiki](https://develop.openfoam.com/Development/openfoam/-/wikis/) and [General wiki](http://wiki.openfoam.com/)
- [Governance](http://www.openfoam.com/governance/), [Governance Projects](https://www.openfoam.com/governance/projects)
Andrew Heather's avatar
Andrew Heather committed
214
- [Contacting OpenCFD](http://www.openfoam.com/contact/)
Andrew Heather's avatar
Andrew Heather committed
215

216
Copyright 2016-2021 OpenCFD Ltd