Skip to content

GitLab

  • Menu
Projects Groups Snippets
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in
  • wdata wdata
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 4
    • Issues 4
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 0
    • Merge requests 0
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Monitor
    • Monitor
    • Incidents
  • Packages & Registries
    • Packages & Registries
    • Package Registry
    • Container Registry
    • Infrastructure Registry
  • Analytics
    • Analytics
    • CI/CD
    • Repository
    • Value stream
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • wtools
  • wdatawdata
  • Wiki
  • wdata format concept

wdata format concept · Changes

Page history
Update wdata format concept authored Jun 23, 2025 by Gabriel Wlazłowski's avatar Gabriel Wlazłowski
Hide whitespace changes
Inline Side-by-side
wdata-format-concept.md
View page @ 99767bd2
[[_TOC_]]
# Introduction # Introduction
**W-data** was designed to satisfy the following requirements: **W-data** was designed to satisfy the following requirements:
* Binary data is stored in a **conceptually easy format** that allows a variety of tools/languages to be used. * Binary data is stored in a **conceptually easy format** that allows a variety of tools/languages to be used.
...@@ -89,14 +90,56 @@ The `sizeB` depends on the data type ...@@ -89,14 +90,56 @@ The `sizeB` depends on the data type
| `vector(d)`, `vector8(d)` |8\*d| d-vector dimensionality, d=1,2,3(default) | | `vector(d)`, `vector8(d)` |8\*d| d-vector dimensionality, d=1,2,3(default) |
| `vector4(d)` |4\*d| d-vector dimensionality, d=1,2,3(default) | | `vector4(d)` |4\*d| d-vector dimensionality, d=1,2,3(default) |
Note that for vector variables, we use the following storage pattern: ## Scalars: real
![vecvar](uploads/39114e8349cccd7fb5f2f514dfcbfa77/vecvar.png) Real variables are stored as single-dimensional arrays, where we use the following prescription of the coordinate decoding
```c
// lattice indicase
int ix=...; // ix in [0,nx)
int iy=...; // iy in [0,ny)
int iz=...; // iz in [0,nz)
// coordinate decoding
double x = x0 + dx*ix;
double y = y0 + dy*iy;
double z = z0 + dz*iz;
// array index
int ixyz = iz + nz*iy + nz*ny*ix;
double *var; // pointer to real array
var[ixyz]=...; // value for the given coordinate
```
## Scalars: complex
The complex variables are stored as pairs of two real numbers: real and imaginary parts. To store the complex variables, we use native C types `double complex` or `float complex`. These are structures with two double/float fields.
```c
// array index
int ixyz = iz + nz*iy + nz*ny*ix;
double complex *varC; // pointer to real array
varC[ixyz]=1.0 + 2.0*I; // complex value for the given coordinate
// or you can cast it to a real array of size 2*nx*ny*nz
double *var = (double*)varC;
var[2*ixyz+0]=1.0; // real part
var[2*ixyz+1]=2.0; // imaginary part
```
## Vectors
For vector variables, we do not introduce a new structure. Instead, we store components of vector variables in separate arrays, placed one by one. The number of components is given in the parentheses at the end of the type name `vector(d)`. If the number of components is not given, the default value `d=3` is assumed. Thus, `vector` is equivalent to `vector(3)`. The vector variable of type `vector(1)` becomes equivalent to `real`.
The storage pattern for a `vector(3)` variable is shown below:
![vecvar](uploads/39114e8349cccd7fb5f2f514dfcbfa77/vecvar.png)
However, we have implemented single-precision (`float` in C notation) types denoted as `real4`, `complex8`, and `vector4`. To be consistent with the notation, one can use `real8`, `complex16` or `vector8` exchangeable for `real`, `complex`, `vector`. Below example of an element decoding
```c
// For 3d vector v = [v_x(x,y,z), v_y(x,y,z), v_z(x,y,z)]
double *var; // pointer to real array
dataV[ixyz + 0 * blocklength] = v_x; //
dataV[ixyz + 1 * blocklength] = v_y;
dataV[ixyz + 2 * blocklength] = v_z;
```
To compute time associated with a given `icycle`, we use the formula ## Time
To compute the time associated with a given `icycle`, we use the formula
``` ```
time = t0 + dt * icycle; time = t0 + dt * icycle;
``` ```
...@@ -104,17 +147,21 @@ If `dt` is negative then `time` parameter has to be extracted from the additiona ...@@ -104,17 +147,21 @@ If `dt` is negative then `time` parameter has to be extracted from the additiona
Let's get back to the `*wtxt` file. Let's get back to the `*wtxt` file.
# Tags
W-data format allows for the representation of the following elements: W-data format allows for the representation of the following elements:
* *variable*:
## Variables
Each variable is represented by the binary file of name `prefix_varname.format`. The variable description has the following format: Each variable is represented by the binary file of name `prefix_varname.format`. The variable description has the following format:
``` ```
var name type unit format var name type unit format
``` ```
The following formats are allowed: The following formats are allowed:
* `wdat`: default format for WSLDA codes. Binary files contain row data (no header). * `wdat`: default format for WSLDA codes. Binary files contain row data (no header).
* `dpca`: (*deprecated*) previous format of cold atomic codes. The binary file contains a header of size 68B where additional info about file content is stored. For this format, *wdata* lib provides only reading functionality. * `npy`: binary files are *numpy* arrays. (_C library supports only read mode._)
* `npy`: binary files are *numpy* arrays. **Functionality under construction** * `dpca`: (*deprecated*) previous format of cold atomic codes. The binary file contains a header of size 68B, where additional info about the file content is stored. For this format, *wdata* lib provides only reading functionality.
* *link*:
## Links
It is an alternative name for a given variable. The entry has a form It is an alternative name for a given variable. The entry has a form
``` ```
link alternative-name var-name link alternative-name var-name
...@@ -123,15 +170,19 @@ Frequently, users call the same variable differently. For example, the user crea ...@@ -123,15 +170,19 @@ Frequently, users call the same variable differently. For example, the user crea
``` ```
var density real none wdat var density real none wdat
``` ```
while another user, in his/her code, uses the name `rho` for the same variable. To maintain the operativity of the code that uses the variable `rho`, the second user can add an entry to `*wtxt` file as a form while another user, in his/her code, uses the name `rho` for the same variable. To maintain the operability of the code that uses the variable `rho`, the second user can add an entry to `*wtxt` file in the form
``` ```
link rho density link rho density
``` ```
* *constant*:
Typically, besides variables, we have some useful constants during the data analysis process. ## Constants
To provide values of selected constants, we use `const` field. For example: Typically, besides variables, we have some useful constants during the data analysis process. To provide values of selected constants, we use `const` field. The syntax is
```
const name value unit
```
For example:
``` ```
const eF 0.5 const eF 0.5
``` ```
See [here](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/wikis/Tags) for a complete list of tags. See [here](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/wikis/Tags) for a complete list of tags.
\ No newline at end of file
Clone repository
  • Examples
    • C examples
    • Python examples
  • VisIt plugin compilation
  • Visit integration
  • Home
  • wdata format concept