# VTKFortran
>#### Pure Fortran VTK XML API
>a pure Fortran 2008 OOP library for writing and reading files conforming the [VTK](http://www.vtk.org/) XML standard.
[](https://github.com/szaghi/VTKFortran/tags)
[](https://github.com/szaghi/VTKFortran/issues)
[](https://github.com/szaghi/VTKFortran/actions/workflows/ci.yml)
[](https://github.com/szaghi/VTKFortran/actions/workflows/ci.yml)
[](#copyrights)
| ๐ **VTK Topologies** Image (`.vti`), Rectilinear (`.vtr`), Structured (`.vts`), and Unstructured (`.vtu`) grids, polygonal data (`.vtp`); composite multi-block (`.vtm`), parallel partitioned (`.pvti`, `.pvtr`, `.pvts`, `.pvtu`, `.pvtp`) datasets, and time series (`.pvd`) | ๐๏ธ **Output Formats** ASCII, Base64-encoded binary, and raw binary appended; optional zlib compression of binary data; VTKHDF (one HDF5 file: every topology, time series, multi-block; optional HDF5); every file read back with `action='read'` | โก **Parallel Writers** MPI ranks write their own files at the same time; OpenMP threads too with ifx or nvfortran (not gfortran: a compiler bug) | ๐จ **OOP Design** Polymorphic `xml_writer` allocated at runtime, `xml_reader` to read back; `vtk_file`, `pvtk_file`, `vtm_file`, `pvd_file` expose a clean type-bound-procedure API |
|:---:|:---:|:---:|:---:|
| ๐ข **All Numeric Kinds** All PENF kinds (`I1P`โ`I8P`, `R4P`โ`R8P`) and array ranks 1โ4 supported in data arrays | โ **Error Codes** Every function returns an integer status โ zero means success | ๐ **Multi-licensed** GPL v3 ยท BSD 2/3-Clause ยท MIT | ๐ฆ **Multiple build systems** CMake, FoBiS.py, fpm |
>#### [Documentation](https://szaghi.github.io/VTKFortran/)
> For full documentation (guide, API reference, usage examples, etc.) see the [VTKFortran website](https://szaghi.github.io/VTKFortran/).
---
## Authors
- Stefano Zaghi โ [@szaghi](https://github.com/szaghi)
Contributions are welcome โ see the [Contributing](https://szaghi.github.io/VTKFortran/guide/contributing) page.
## Copyrights
This project is distributed under a multi-licensing system:
- **FOSS projects**: [GPL v3](http://www.gnu.org/licenses/gpl-3.0.html)
- **Closed source / commercial**: [BSD 2-Clause](http://opensource.org/licenses/BSD-2-Clause), [BSD 3-Clause](http://opensource.org/licenses/BSD-3-Clause), or [MIT](http://opensource.org/licenses/MIT)
> Anyone interested in using, developing, or contributing to this project is welcome โ pick the license that best fits your needs.
---
## Quick start
```fortran
use vtk_fortran, only : vtk_file
use penf, only : I4P, R8P
implicit none
type(vtk_file) :: a_vtk_file
integer, parameter :: nx1=0, nx2=9, ny1=0, ny2=5, nz1=0, nz2=5
integer, parameter :: nn=(nx2-nx1+1)*(ny2-ny1+1)*(nz2-nz1+1)
real(R8P) :: x(nx1:nx2,ny1:ny2,nz1:nz2)
real(R8P) :: y(nx1:nx2,ny1:ny2,nz1:nz2)
real(R8P) :: z(nx1:nx2,ny1:ny2,nz1:nz2)
real(R8P) :: v(nx1:nx2,ny1:ny2,nz1:nz2)
integer :: error
error = a_vtk_file%initialize(format='binary', filename='output.vts', &
mesh_topology='StructuredGrid', &
nx1=nx1, nx2=nx2, ny1=ny1, ny2=ny2, nz1=nz1, nz2=nz2)
error = a_vtk_file%xml_writer%write_piece(nx1=nx1, nx2=nx2, ny1=ny1, ny2=ny2, nz1=nz1, nz2=nz2)
error = a_vtk_file%xml_writer%write_geo(n=nn, x=x, y=y, z=z)
error = a_vtk_file%xml_writer%write_dataarray(location='node', action='open')
error = a_vtk_file%xml_writer%write_dataarray(data_name='pressure', x=v, one_component=.true.)
error = a_vtk_file%xml_writer%write_dataarray(location='node', action='close')
error = a_vtk_file%xml_writer%write_piece()
error = a_vtk_file%finalize()
```
See [`src/tests/`](src/tests/) for more examples covering rectilinear, unstructured, multi-block, parallel, and volatile XML output.
---
## Install
### One-line install
```bash
curl -fsSL https://github.com/szaghi/VTKFortran/releases/latest/download/install.sh | bash
```
It installs the latest release into `~/.local` with the build system you choose among those VTKFortran ships
(`--build fobis|fpm|cmake`: a menu asks when you do not say), the compiler you name (`--fc`, `--gnu`, `--intel`), one
install per compiler (`lib/vtkfortran/-/`, `include/vtkfortran/-/`), and makes it
usable through pkg-config (`pkg-config --cflags --libs vtkfortran`, with `PKG_CONFIG_PATH=$HOME/.local/lib/pkgconfig`).
The release carries VTKFortran's dependencies (BeFoR64, FACE, FoXy, PENF, StringiFor), so CMake needs no network. It
builds the library without the optional zlib and HDF5 (VTKHDF) support: for those, build VTKFortran as below. Pass
options after `bash -s --`, e.g. `... | bash -s -- --build cmake --prefix /opt/vtkfortran`; `--help` lists them all,
`--uninstall` removes the install. The installer is FoBiS's
([One-line installer](https://szaghi.github.io/FoBiS/cookbook/installer)).
### CMake
**Clone, build, and test:**
```bash
git clone https://github.com/szaghi/VTKFortran
cd VTKFortran
fobis fetch # dependencies into src/third_party/ (pip install FoBiS.py)
cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build && ctest --test-dir build
```
**As a subdirectory dependency** โ place a clone (with its dependencies fetched) alongside your sources and add to your `CMakeLists.txt`:
```cmake
add_subdirectory(VTKFortran)
target_link_libraries(your_target VTKFortran::VTKFortran)
```
### FoBiS.py
```bash
git clone https://github.com/szaghi/VTKFortran && cd VTKFortran
fobis fetch # dependencies into src/third_party/
fobis build --mode static-gnu # static library
fobis build --mode tests-gnu # build and place tests in ./exe/
scripts/run_tests.sh # run tests
```
### fpm
Requires at least version v0.13.0!
Building library in current directory
```bash
fpm build --compiler gfortran/ifx/... --profile release
```
The library may be installed to a custom location with
```bash
fpm install --compiler gfortran/ifx/... --profile release --prefix /target_path
```
Please refer to the `fpm.toml` file for further available profiles and features.