.\" $Header$
.nr yr \n(yr+1900
.af mo 01
.af dy 01
.TH ncmpidump 1 "PnetCDF 1.14.1" "Printed: \n(yr-\n(mo-\n(dy" "PnetCDF utilities"
.SH "نام (NAME)"
ncmpidump \- تبدیل فایل‌های netCDF به قالب اسکی (CDL)
.SH "خلاصه دستور (SYNOPSIS)"
.ft B
.HP
ncmpidump
.nh
\%[-ch]
\%[-v \fIvar1,...\fP]
\%[-b \fIlang\fP]
\%[-f \fIlang\fP]
\%[-l \fIlen\fP]
\%[-n \fIname\fP]
\%[-p \fIf_digits[,d_digits]\fP]
\%\fIfile\fP
.br
.ft B
.HP
ncmpidump
.nh
\%-k
\%\fIfile\fP
.hy
.ft
.SH "توضیحات (DESCRIPTION)"
دستور \fBncmpidump\fP یک نمایش اسکی (ASCII) از فایل netCDF مشخص‌شده را در خروجی استاندارد تولید می‌کند. این نمایش اسکی در قالبی به نام CDL (\(lqnetwork Common Data form Language\(rq) است که می‌توان آن را مشاهده و ویرایش کرد یا به عنوان ورودی به \fBncmpigen\fP داد. برنامهٔ \fBncmpigen\fP ابزاری همراه است که می‌تواند یک فایل باینری netCDF را از روی یک فایل CDL تولید کند. از این رو \fBncmpigen\fP و \fBncmpidump\fP می‌توانند به صورت معکوس یکدیگر برای تبدیل نمایش داده‌ها میان نمایش‌های باینری و اسکی به کار روند. برای شرح نمایش‌های CDL و netCDF به \fBncmpigen\fP مراجعه کنید.
.LP
همچنین می‌توان با گزینهٔ \-k از \fBncmpidump\fP برای تعیین نوع فایل netCDF استفاده‌شده (کدام گونه از قالب فایل netCDF) بهره برد.
.LP
دستور \fBncmpidump\fP یک قالب پیش‌فرض برای هر نوع دادهٔ netCDF تعریف می‌کند، اما در صورتی که مشخصهٔ \(aqC_format\(aq برای یک متغیر netCDF تعریف شده باشد، این رفتار قابل تغییر است. در این صورت، \fBncmpidump\fP از مشخصهٔ \(aqC_format\(aq برای قالب‌بندی هر مقدار استفاده خواهد کرد. برای نمونه، اگر مشخص باشد که داده‌های ممیز شناور برای متغیر netCDF به نام \(aqZ\(aq تنها تا سه رقم بامعنی دقیق هستند، استفاده از این مشخصهٔ متغیر مناسب خواهد بود:
.RS
.HP
Z:C_format = "%.3g"
.RE
.LP
همچنین می‌توان از \fBncmpidump\fP به عنوان یک مرورگر ساده برای فایل‌های دادهٔ netCDF استفاده کرد، تا نام‌ها و اندازه‌های ابعاد؛ نام‌ها، انواع و شکل‌های متغیرها؛ نام‌ها و مقادیر مشخصه‌ها؛ و در صورت تمایل، مقادیر داده‌ها را برای همهٔ متغیرها یا متغیرهای برگزیده در یک فایل netCDF نمایش دهد.
.LP
دستور \fBncmpidump\fP از \(aq_\(aq برای نمایش مقادیر داده‌ای استفاده می‌کند که برابر با مشخصهٔ \(aq_FillValue\(aq برای یک متغیر هستند، که هدف از آن نشان دادن داده‌هایی است که هنوز نوشته نشده‌اند. اگر یک متغیر فاقد مشخصهٔ \(aq_FillValue\(aq باشد، چنانچه متغیر از نوع بایتی (byte) نباشد، از مقدار پرکنندهٔ پیش‌فرض برای نوع آن متغیر استفاده می‌شود.
.SH "گزینه‌ها (OPTIONS)"
.IP "\fB-c\fP"
نمایش مقادیر متغیرهای \fIمختصات\fP (متغیرهایی که خود بُعد نیز هستند) و همچنین اعلان‌های همهٔ ابعاد، متغیرها و مقادیر مشخصه‌ها. مقادیر داده‌ای متغیرهای غیرمختصاتی در خروجی گنجانده نمی‌شوند. این مناسب‌ترین گزینه برای داشتن نگاهی اجمالی به ساختار و محتویات یک فایل netCDF است.
.IP "\fB-h\fP"
تنها نمایش اطلاعات \fIسرآیند\fP (header) در خروجی؛ یعنی اعلان‌های ابعاد، متغیرها و مشخصه‌ها بدون مقادیر داده برای هیچ متغیری. خروجی همانند استفاده از گزینهٔ \fB-c\fP است، با این تفاوت که مقادیر متغیرهای مختصات در آن گنجانده نمی‌شوند. (حداکثر یکی از گزینه‌های \fB-c\fP یا \fB-h\fP می‌تواند مشخص شود.)
.IP "\fB-v\fP \fIvar1,...,varn\fP"
خروجی علاوه بر اعلان‌های همهٔ ابعاد، متغیرها و مشخصه‌ها، شامل مقادیر داده‌ها برای متغیرهای مشخص‌شده خواهد بود. یک یا چند متغیر باید بر اساس نام در فهرستی با جداکنندهٔ ویرگول پس از این گزینه مشخص شوند. این فهرست باید یک آرگومان واحد برای دستور باشد، بنابراین نمی‌تواند شامل فاصله یا سایر نویسه‌های فضای خالی باشد. متغیرهای نام‌برده باید متغیرهای معتبر netCDF در فایل ورودی باشند. حالت پیش‌فرض بدون این گزینه و در صورت نبود گزینه‌های \fB-c\fP یا \fB-h\fP، شامل کردن مقادیر داده‌ها برای \fIهمهٔ\fP متغیرها در خروجی است.
.IP "\fB-b\fP \fIlang\fP"
یک یادداشت مختصر در قالب یک کامنت CDL (متنی که با نویسه‌های \(lq//\(rq آغاز می‌شود) در بخش داده‌های خروجی برای هر \(aqسطر\(aq داده گنجانده می‌شود تا به شناسایی مقادیر داده برای متغیرهای چندبُعدی کمک کند. اگر \fIlang\fP با \(aqC\(aq یا \(aqc\(aq آغاز شود، از قواعد زبان C استفاده خواهد شد (نمایه‌های مبتنی بر صفر، سریع‌ترین تغییر در آخرین بُعد). اگر \fIlang\fP با \(aqF\(aq یا \(aqf\(aq آغاز شود، از قواعد زبان Fortran استفاده خواهد شد (نمایه‌های مبتنی بر یک، سریع‌ترین تغییر در نخستین بُعد). در هر دو حالت، داده‌ها با همان ترتیب نمایش داده خواهند شد؛ تنها یادداشت‌ها متفاوت خواهند بود. این گزینه برای مرور حجم‌های بزرگ داده‌های چندبُعدی مفید است.
.IP "\fB-f\fP \fIlang\fP"
یادداشت‌های کامل در قالب کامنت‌های انتهایی CDL (متنی که با نویسه‌های \(lq//\(rq آغاز می‌شود) برای تک‌تک مقادیر داده (به‌جز نویسه‌های تکی در آرایه‌های نویسه‌ای) در بخش داده‌ها گنجانده خواهد شد. اگر \fIlang\fP با \(aqC\(aq یا \(aqc\(aq آغاز شود، از قواعد زبان C استفاده خواهد شد (نمایه‌های مبتنی بر صفر، سریع‌ترین تغییر در آخرین بُعد). اگر \fIlang\fP با \(aqF\(aq یا \(aqf\(aq آغاز شود، از قواعد زبان Fortran استفاده خواهد شد (نمایه‌های مبتنی بر یک، سریع‌ترین تغییر در نخستین بُعد). در هر دو حالت، داده‌ها با همان ترتیب نمایش داده خواهند شد؛ تنها یادداشت‌ها تفاوت خواهند داشت. این گزینه می‌تواند برای هدایت داده‌ها با لوله‌کشی (pipe) به سایر فیلترها مفید باشد، چرا که هر مقدار داده روی سطری جداگانه و با شناسایی کامل قرار می‌گیرد.
.IP "\fB-l\fP \fIlen\fP"
تغییر حداکثر طول خط پیش‌فرض (80) که در قالب‌بندی فهرست‌های مقادیر داده‌های غیرنویسه‌ای استفاده می‌شود.
.IP "\fB-n\fP \fIname\fP"
قالب CDL به نامی برای یک مجموعه‌دادهٔ netCDF نیاز دارد تا توسط \fBncmpigen -b\fP در تولید نام پیش‌فرض فایل netCDF به کار رود. به‌طور پیش‌فرض، \fIncmpidump\fP این نام را از آخرین جزء مسیر فایل netCDF ورودی با حذف هرگونه پسوند آن می‌سازد. از گزینهٔ \fB-n\fP برای مشخص کردن نامی دیگر استفاده کنید. اگرچه نام فایل خروجی استفاده‌شده توسط \fBncmpigen -b\fP قابل تعیین است، اما عاقلانه است که با \fIncmpidump\fP نام پیش‌فرض تغییر یابد تا هنگام استفاده از \fBncmpidump\fP، ویرایش فایل CDL حاصل و استفاده از \fBncmpigen -b\fP برای تولید فایل جدید netCDF از روی فایل ویرایش‌شده، از بازنویسی تصادفی یک فایل باارزش netCDF جلوگیری شود.
.IP "\fB-p\fP \fIfloat_digits[,double_digits]\fP"
دقت پیش‌فرض (تعداد ارقام بامعنی) را برای نمایش مقادیر داده‌های ممیز شناور (floating-point) یا دقت مضاعف (double precision) برای مشخصه‌ها و متغیرها مشخص می‌کند. در صورت تعیین، این مقدار جایگزین مقدار مشخصهٔ \(aqC_format\(aq برای هر متغیری که دارای چنین مشخصه‌ای باشد می‌شود. داده‌های ممیز شناور با \fIfloat_digits\fP رقم بامعنی نمایش داده خواهند شد. اگر \fIdouble_digits\fP نیز مشخص شده باشد، مقادیر دقت مضاعف با همان تعداد ارقام بامعنی نمایش خواهند یافت. در صورت عدم تعیین مشخصات \fB-p\fP، داده‌های ممیز شناور و دقت مضاعف به ترتیب با 7 و 15 رقم بامعنی نمایش داده می‌شوند. در صورتی که دقت کمتری لازم باشد، می‌توان فایل‌های CDL را کم‌حجم‌تر ساخت. اگر هر دو دقت ممیز شناور و دقت مضاعف مشخص شده باشند، دو مقدار باید با ویرگول (بدون فاصله) و به عنوان یک آرگومان واحد به دستور داده شوند. اگر واقعاً می‌خواهید تمام تک‌تک بیت‌های دقت فایل netCDF در فایل CDL برای همهٔ مقادیر ممکن ممیز شناور بازنمایی شوند، باید آن را با \fB-p 9,17\fP مشخص کنید (بر اساس قضیهٔ 15 مقاله‌ای که در بخش مراجع فهرست شده است).
.IP "\fB-k\fP"
نوع فایل netCDF را گزارش می‌کند: classic، ‏64-bit offset یا 64-bit data.
پیش از نسخهٔ 3.6 netCDF، تنها یک نوع فایل netCDF وجود داشت که با عنوان \(aqclassic\(aq (همچنین معروف به گونهٔ قالب 1 یا CDF-1) شناخته می‌شد.
پشتیبانی از فایل‌های حجیم گونهٔ دیگری از این قالب را معرفی کرد که با عنوان \(aq64-bit offset\(aq (شناخته‌شده به عنوان گونهٔ قالب 2 یا CDF-2) مشخص می‌شود.
پشتیبانی از داده‌های حجیم گونهٔ دیگری از قالب را معرفی کرد که با عنوان \(aq64-bit data\(aq (شناخته‌شده به عنوان گونهٔ قالب 5 یا CDF-5) شناخته می‌شود.

.SH "مثال‌ها (EXAMPLES)"
.LP
بررسی ساختار داده‌ها در فایل netCDF به نام \(aq\fBfoo.nc\fP\(aq:
.RS
.HP
ncmpidump -c foo.nc
.RE
.LP
تولید یک نسخهٔ یادداشت‌دار CDL از ساختار و داده‌های درون فایل netCDF به نام \(aq\fBfoo.nc\fP\(aq، با استفاده از نمایه‌گذاری به سبک C برای یادداشت‌ها:
.RS
.HP
ncmpidump -b c foo.nc > foo.cdl
.RE
.LP
خروجی دادن داده‌ها تنها برای متغیرهای \(aquwind\(aq و \(aqvwind\(aq از فایل netCDF به نام \(aq\fBfoo.nc\fP\(aq، و نمایش داده‌های ممیز شناور تنها با سه رقم بامعنی از دقت:
.RS
.HP
ncmpidump -v uwind,vwind -p 3 foo.nc
.RE
.LP
تولید یک فهرست با یادداشت‌گذاری کامل (یک مقدار داده در هر سطر) از داده‌ها برای متغیر \(aqomega\(aq، با استفاده از قواعد زبان Fortran برای نمایه‌ها، و تغییر دادن نام مجموعه‌دادهٔ netCDF در فایل CDL حاصل به \(aqomega\(aq:
.RS
.HP
ncmpidump -v omega -f fortran -n omega foo.nc > Z.cdl
.RE
.SH "مراجع (REFERENCES)"
\fIWhat Every Computer Scientist should Know About Floating-Point Arithmetic\fP, D. Goldberg, \fBACM Computing Surveys, Vol. 23, No. 1\fP, March 1991, pp. 5-48.

.SH "همچنین ببینید (SEE ALSO)"
.LP
.BR ncmpigen (1),
.BR pnetcdf (3)
.SH "تاریخ (DATE)"
۳۱ ژوئیه ۲۰۲۵
.SH "گزارش باگ‌ها (BUGS)"
.LP
با آرایه‌های نویسه‌ای که حاوی بایت تهی (null-byte) هستند همانند رشته‌های C رفتار می‌شود، بنابراین هیچ نویسه‌ای پس از بایت تهی در خروجی ظاهر نخواهد شد.

آرایه‌های چندبُعدی رشته‌های نویسه‌ای به خوبی مدیریت نمی‌شوند، چرا که نحو CDL برای شکستن یک رشتهٔ نویسه‌ای طولانی به چندین سطر کوتاه‌تر ضعیف است.

باید راهی وجود داشته باشد تا مشخص شود داده‌ها باید به ترتیب \(aqرکورد\(aq نمایش داده شوند، یعنی تمام مقادیر متغیرهای رکوردی که بعد رکورد یکسانی دارند در کنار هم قرار گیرند.