The documentation of “3d_data/structure.h”

3d_data/structure.h マニュアル

(The documentation of 3d_data/structure.h)

Last Update: 2021/12/2

3d_data/structure.hでは 3d_dataヘッダファイルパッケージで主に用いる構造体が定義されている。各構造体の定義を以下に示す。
Structures mainly used in 3d_data header file package are defined in 3d_data/structure.h. Definitions of individual structures are shown below.

◆目次(Table of contents)

struct _3d_data型構造体 (a struct _3d_data-type structure)
struct _3d_data_index型構造体 (a struct _3d_data_index-type structure)

◆struct _3d_data型構造体 (A struct _3d_data-type structure)

3次元データを表現するための構造体である。 3次元データは\(x\), \(y\), \(z\)方向それぞれに一定間隔で配置した格子点 \[\begin{equation} x=x_0+i\Delta x \hspace{1em} (i=0,1,2,\cdots,N_x-1) \label{eq.grid_node_x} \end{equation}\] \[\begin{equation} y=y_0+j\Delta y \hspace{1em} (j=0,1,2,\cdots,N_y-1) \label{eq.grid_node_y} \end{equation}\] \[\begin{equation} z=z_0+k\Delta z \hspace{1em} (k=0,1,2,\cdots,N_z-1) \label{eq.grid_node_z} \end{equation}\] において定義される。ここで

\(N_x\), \(N_y\), \(N_z\)は \(x\), \(y\), \(z\)方向の格子点数を表す整数定数
\(x_0\), \(y_0\), \(z_0\)は \(x\), \(y\), \(z\)方向のデータ定義範囲の下端を表す実定数
\(\Delta x\), \(\Delta y\), \(\Delta z\)は \(x\), \(y\), \(z\)方向の格子点間隔を表す実定数

である。このようなデータを表現するため、 struct _3d_data型構造体は以下のメンバから成る。
A structure to represent a 3-D data. The 3-D data is defined on grid nodes deployed at constant intervals along \(x\)-, \(y\)-, and \(z\)-directions. The grid node locations are given by eqs. (\ref{eq.grid_node_x})-(\ref{eq.grid_node_z}), where

\(N_x\), \(N_y\), and \(N_z\) are integer constants which denote the numbers of grid nodes along the \(x\)-, \(y\)-, and \(z\)-directions;
\(x_0\), \(y_0\), and \(z_0\) are real constants which denote the lower bounds of the data definition ranges along the \(x\)-, \(y\)-, and \(z\)-directions; and
\(\Delta x\), \(\Delta y\), and \(\Delta z\) are real constants which denote the grid intervals along the \(x\)-, \(y\)-, and \(z\)-directions, respectively.

To express this data structure, struct _3d_data-type structure is composed of the following members.

型 Type	メンバ名 Name of member	メンバの意味 Meaning of member
int	N[3]	各座標軸方向の格子点数。 N[0]\(=N_x\) N[1]\(=N_y\) N[2]\(=N_z\) である。 The numbers of grid nodes in individual directions along the coordinate axes, defined such that N[0]\(=N_x\), N[1]\(=N_y\), and N[2]\(=N_z\).
double	x0[3]	各座標軸方向のデータ定義範囲の下端。 x0[0]\(=x_0\) x0[1]\(=y_0\) x0[2]\(=z_0\) である。 The lower bounds of the data definition ranges in individual directions along the coordinate axes, defined such that x0[0]\(=x_0\), x0[1]\(=y_0\), and x0[2]\(=z_0\).
double	dx[3]	各座標軸方向の格子点間隔。 dx[0]\(=\Delta x\) dx[1]\(=\Delta y\) dx[2]\(=\Delta z\) である。 The grid intervals in individual directions along the coordinate axes, defined such that dx[0]\(=\Delta x\), dx[1]\(=\Delta y\), and dx[2]\(=\Delta z\).
double	xmax[3]	各座標軸方向のデータ定義範囲の上端。 xmax[0]\(=x_0+(N_x-1)\Delta x\) xmax[1]\(=y_0+(N_y-1)\Delta y\) xmax[2]\(=z_0+(N_z-1)\Delta z\) であり、これらはそれぞれ\(x\), \(y\), \(z\)方向のデータ定義範囲の上端を表す。 The upper bounds of the data definition ranges in individual directions along the coordinate axes, defined such that xmax[0]\(=x_0+(N_x-1)\Delta x\), xmax[1]\(=y_0+(N_y-1)\Delta y\), and xmax[2]\(=z_0+(N_z-1)\Delta z\), which represent the upper bounds of the data definition ranges in \(x\)-, \(y\)-, and \(z\)-directions, respectively.
int ∗∗∗	index	格子点におけるメンバvalueの配列要素番号のリスト。要素数\(N_x\times N_y\times N_z\)の3次元配列であり、格子点番号\((i,j,k)\)の位置 ((\ref{eq.grid_node_x})-(\ref{eq.grid_node_z})式参照) におけるメンバvalueの配列要素番号をindex[i][j][k]で与える。 index[i][j][k]\(=iN_yN_z+jN_z+k\) であり、現在ではマクロ_3dindexで代用できる。 List of array component indices of member value at the grid nodes. This is a 3-D array of \(N_x\times N_y\times N_z\) components, and the array component index of member value at a location of \((i,j,k)\)th grid node (see eqs. (\ref{eq.grid_node_x})-(\ref{eq.grid_node_z})) is given by index[i][j][k]. The value is: index[i][j][k]\(=iN_yN_z+jN_z+k\) and currently this value can alternatively be obtained by a macro _3dindex.
double ∗	value	格子点における3次元データの値のリスト。要素数\(N_xN_yN_z\)の1次元配列であり、格子点番号\((i,j,k)\)の位置 ((\ref{eq.grid_node_x})-(\ref{eq.grid_node_z})式参照) における3次元データの値をvalue[\(iN_yN_z+jN_z+k\)]で与える。配列要素番号はこのように数式で書くよりもマクロ_3dindexあるいはメンバindexを用いて指定するのが分かりやすい。例えば構造体名をdataとすると data.value[_3dindex(data,i,j,k)] あるいは data.value[data.index[i][j][k]] のように値を参照できる。 List of the values of the 3-D data at the grid nodes. This is a 1-D array of \(N_xN_yN_z\) components, and the value of the 3-D data at a location of \((i,j,k)\)th grid node (see eqs. (\ref{eq.grid_node_x})-(\ref{eq.grid_node_z})) is given by value[\(iN_yN_z+jN_z+k\)]. Instead of using the explicit formula for the array component index, a macro _3dindex and the member index are available. For example, if the name of the structure is data, then the data value can be referred to as data.value[_3dindex(data,i,j,k)] or data.value[data.index[i][j][k]].
char	checked[1]	構造体が正しい構造になっていることをチェック済みか否かを示すフラグ。正しい構造とは例えば格子点数が正である、メンバindexやvalueが配列として動的メモリが確保されている(NULLではない)、など構造体が3次元データを表すと見なせるように各メンバの値が適切に設定されていることを指す。チェック済みの場合: ’y’ 未チェックの場合: ’n’ である。 A flag indicating whether the structure has been checked that the members are properly set to represent a 3-D data; for example, whether the numbers of grid nodes are positive, and whether the dynamic memories have been allocated for members index and value (i.e., they are not NULL). The value of this member is: ’y’ if the structure has been checked, ’n’ otherwise.

◆struct _3d_data_index型構造体 (A struct _3d_data_index-type structure)

3次元データを構成する格子点のうち、特定の用途に用いる格子点のグループを表す構造体である。このグループは多数のサブグループから成り、各サブグループは同数の格子点から構成される。
A structure to represent a group of grid nodes of a 3-D data used for a specific purpose. The group is composed of many sub groups, each of which is composed of the same number of grid nodes.

この構造体の利用例として「3次元データの定義範囲の端に位置する全ての格子点での値をその1つ内側の格子点での値と等しくする」という処理を考える。この処理を行うには「端に位置する格子点」と「その1つ内側の格子点」のペアをサブグループとしてまとめておき、それらのサブグループ一式をひとまとめにしてこの構造体に入れておく。例えば

サブグループ1: 格子点(0,1,1)と(1,1,1)
サブグループ2: 格子点(0,2,1)と(1,2,1)
サブグループ3: 格子点(0,3,1)と(1,3,1)
…

といった具合である。そうすれば

for(サブグループ){
サブグループ内の1つ目の要素の値=2つ目の要素の値;
}

のようにして処理を実行できる。境界面が6つあるので本来ならば似たような処理を6回書かなければならなかったところ、この構造体を用いることで1回のループで済ませられる点がポイントである。
As an example, consider to make the value of each grid node on the edge of the definition range of a 3-D data to be equal to the value of the grid node immediately inside of it. To realize it, first construct sub groups, each of which consists of “a grid node on the edge” and “the grid node immediately inside of it”. Then merge all of these sub groups into this structure. For example,

sub group 1: grid nodes (0,1,1) and (1,1,1),
sub group 2: grid nodes (0,2,1) and (1,2,1),
sub group 3: grid nodes (0,3,1) and (1,3,1),
…

Then the processing is implemented in a way as:

for(sub group){
the value of the 1st component in this sub group = the value of the 2nd component in this sub group;
}

The point is that only one loop is needed, while six similar loops would have been needed without this structure as there are six boundaries.

この構造体は以下のメンバから成る。
This structure is composed of the following members.

型 Type	メンバ名 Name of member	メンバの意味 Meaning of member
int	number1	サブグループの個数。 The number of sub groups.
int	number2	各サブグループを構成する格子点数。 The number of grid nodes in each sub group.
int ∗∗	index	グループを構成する格子点のリスト。要素数number1×number2の2次元配列であり、 index[i][j]は\(i\)番目のサブグループ内の\(j\)番目の格子点を表す。各格子点はstruct _3d_data構造体のメンバindexの値として与える。 A list of the grid nodes that constitute the group. This is a 2-D array composed of number1×number2 components, defined such that index[i][j] represents the \(j\)th grid node in the \(i\)th sub group. Each grid node is specified as the value of member index of a struct _3d_data structure.