--- name: "branch" section: "1rheolef" platform: "linux" package: "rheolef" version: "7.2-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/branch" --- # branch(1rheolef) handle a family of fields (rheolef-7.2) ## NAME branch - handle a family of fields (rheolef-7.2) ## SYNOPSIS ``` branch [options] file[.branch[.gz]] ``` ## EXAMPLES Run an animation: ``` branch file.branch ``` It uses either `gnuplot`, for 1d geometries, or `paraview`, otherwise. Next, let us extract the 17-th indexed and save it in `.field` file format. Indexes started at 0: ``` branch file.branch -extract 17 -branch > file-17.field ``` ## DESCRIPTION Read and visualize or output a branch of finite element fields from file. ## INPUT FILE SPECIFICATION filename Specifies the name of the file containing the input field. `-` Read field on standard input instead on a file. `-I`*dir* \\ `-I` *dir* Add *dir* to the Rheolef file search path. This option is useful e.g. when the mesh .geo and the .field files are in different directories. This mechanism initializes a search path given by the environment variable `RHEOPATH`. If the environment variable `RHEOPATH` is not set, the default value is the current directory. `-name` When the field comes from standard input, the file base name is not known and is set to 'output' by default. This option allows one to change this default. Useful when dealing with output formats (graphic, format conversion) that creates auxiliary files, based on this name. ## INPUT FORMAT OPTIONS `-if` *format* \ `-input-format` *format* Load a mesh in the prescribed file *format*. Supported input file formats are: `.branch` and `.vtk`. ## RENDER SPECIFICATION `-gnuplot` Run a 1d animation using `gnuplot`. `-paraview` Run 2d and 3d animations using `paraview`. Generate a collections of `.vtk` files and a main `.py` python one, then execute the python file. ## RENDERING OPTIONS - `-skipvtk` Do not regenerate the collection of `.vtk` files when using the `paraview` render. Only generate the main `.py` python file and execute it. Assume that all the `.vtk` files was already created with the `-vtk` option or with `-paraview` one combined with `-noclean`. - `-color` `-gray` `-black-and-white` `-bw` Use (color/gray scale/black and white) rendering. Color rendering is the default. `-[no]showlabel` Show or hide title, color bar and various annotations. Default is to show labels. - `-label` *string* Set the label to show for the represented value. This supersedes the default value. `-[no]elevation` For a two dimensional field, represent values as elevation in the third dimension. The default is no elevation. `-[no]fill` Isoline intervals are filled with color. This is the default. `-[no]volume` For 3D data, render values using a colored translucid volume. This option requires the `paraview` code. - `-scale` *float* Applies a multiplicative factor to the field. This is useful e.g. in conjunction with the `-elevation` option. The default value is 1. `-[no]stereo` Rendering mode suitable for red-blue anaglyph 3D stereoscopic glasses. This option is only available with `paraview`. `-[no]cut` Cut by a specified plane. The cutting plane is specified by its origin point and normal vector. This option requires `paraview`. `-origin` *float* \[*float* \[*float*\]\] Set the origin of the cutting plane. Default is (0.5, 0.5, 0.5). `-normal` *float* \[*float* \[*float*\]\] Set the normal of the cutting plane. Default is (1, 0, 0). `-isovalue` \[*float*\] \ `-iso` \[*float*\] Draw 2d isoline or 3d isosurface. When the optional float is not provided, a median value is used. This option requires the `paraview` code. - `-noisovalue` Do not draw isosurface. This is the default. - `-n-iso` *int* For 2D visualizations, the isovalue table contains regularly spaced values from fmin to fmax, the bounds of the field. - `-n-iso-negative` *int* The isovalue table is split into negatives and positives values. Assume there is n\_iso=15 isolines: if 4 is requested by this option, then, there will be 4 negatives isolines, regularly spaced from fmin to 0 and 11=15-4 positive isolines, regularly spaced from 0 to fmax. This option is useful when plotting e.g. vorticity or stream functions, where the sign of the field is representative. ## OUTPUT FILE SPECIFICATION `-vtk` Generate a collection of `.vtk` files for `paraview`. `-branch` Output on stdout in `.branch` format. `-extract` *int* \ `-index` *int* Extract the i-th record in the file. The output is a field or multi-field file format. Indexes started at 0. `-toc` Print the table of contents (toc) to standard output and exit. Each index value is followed by the associated value (e.g. the time or a physical parameter). `-ndigit` *int* Number of digits used to print floating point values when using the `-branch` option. Note that the default value depends upon the machine precision associated to the `Float` type, as defined by the `configure` script during the installation of the library (see **configuration**). When `Float` is `double`, then 16 digits are used by default. This default value can be changed by this option, e.g. for the portability of non-regression tests. `-image-format` *string* For image or video capture. The supported argument are .`avi`, .`jpg`, .`png`, .`tif` and .`bmp`. This option should be combined with the `paraview` render. The output file is basename.`avi` where *basename* is the name of the mesh, or can be set with the `-name` option. `-resolution` *int* *int* For the resolution of an image or a video capture. The argument is a couple of sizes, separated by a white space. This option can be used together with the `-image-format` for any of the bitmap image formats. This option requires the `paraview` render. ## OTHERS OPTIONS `-umin` *float* \ `-umax` *float* Set the solution range for the `gnuplot` driver. By default this range is computed from the first field of the branch, and this could be problematic when this field is initialy zero. \`-subdivide *int* When using a high order geometry, the number of points per edge used to draw a curved element. Default value is the mesh order. - `-topography` filename\[.field\[.gz\]\] Performs a tridimensional elevation view based on the topographic data. - `-proj` *approx* `-proj` Convert all selected fields to approximation *approx* by using a L2 projection. When argument is omitted, `P1` approximation is assumed. - `-lumped-proj` Force `P1` approximation for L2 projection and use a lumped mass matrix for it. - `-round` \[*float*\] Round the input up to the specified precision. This option, combined with `-field`, leads to a round filter. Useful for non-regression test purpose, in order to compare numerical results between files with a limited precision, since the full double precision is machine-dependent. `-[no]verbose` Print messages related to graphic files created and command system calls (this is the default). \`-\[no\]clean Clear temporary graphic files (this is the default). `-[no]execute` Execute graphic command (this is the default). The `-noexecute` variant is useful in conjunction with the `-verbose` and `-noclean` options in order to modify some render options by hand. ## EXAMPLE OF FILE FORMAT CONVERSION For conversion from the `.vtk` legacy ascii file format to the `.branch` one, simply writes: ``` branch -if vtk -branch - < input.vtk > output.branch ``` ## THE BRANCH FILE FORMAT The `.branch` file format bases on the `.field` one (see **field(1)** ): ``` example | general format ------------------------------------------------- #!branch | #!branch branch | branch 1 1 11 | time u | | #time 3.14 | # #u | # field | ..... | .... | ..... | .... #time 6.28 | # #u | # field | ..... | .... ``` The key is here `time`, but could be any string without spaces, such as `t` or `lambda`. Labels appears all along the file to facilitate direct jumps and field and step skips. The previous example contained one `field` at each time step. The format supports several fields, such as (t,u(t),p(t)), where u could be a multi-component field (e.g. a vector): ``` #!branch branch 1 2 11 time u p #time 3.14 #u ... #p ... #time 6.28 ... ``` ## IMPLEMENTATION This documentation has been generated from file main/bin/branch.cc ## AUTHOR Pierre Saramito \ ## COPYRIGHT Copyright (C) 2000-2018 Pierre Saramito \ GPLv3+: GNU GPL version 3 or later \. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.