タグ付けされた質問 「documentation」

多くの場合、他の人が書いた科学的コード（または、時には自分の研究でさえ）を継承または遭遇したときに、ドキュメントがまばらであるか存在しないことに気付きました。運が良ければ、有益なコメントが表示されます。運が良ければ、DoxygenのコメントとDoxyfileさえありますので、関数インターフェースといくつかのフォーマットされたHTMLを参照してください。私が非常に幸運なら、Doxygenとソースファイルのコメントに加えてPDFマニュアルと例があります。そして、私は非常に楽しかったです。 ソースコードの文書化に役立つ情報とツールは何ですか？さらに言えば、科学ソフトウェアの場合、そのソースコードに付随するデータと結果を文書化するのにどのような情報とツールが役立ちますか？

44 software  documentation 

私の論文の1つでは、いくつかの数値に加えていくつかの数値結果をリストしています。私がやりたいのは、論文の数値結果が常にコードと一致することを確認することです。今は、シミュレーション結果から数値結果を紙に直接コピーします。これは非常にシンプルでローテクですが、結果を誤ってコピーしたり、紙の結果をコード出力。 論文で引用した数値結果を、コードで生成された結果と同期させる良い方法はありますか？（ここでは、コードを実行することは、論文を更新したいときはいつでも簡単で実用的であると想定しています。）これらの数値結果は、必ずしも表形式に適しているとは限りません。原稿に表がある場合もありますが、より一般的には、方程式の数値としてシミュレーションパラメーターがリストされています。例は次のようになります。 y∗=(y∗1,…,y∗n)y∗=(y1∗,…,yn∗)\begin{align} \mathbf{y}^{*} = (y_{1}^{*}, \ldots, y_{n}^{*}) \end{align} ここで、初期条件の要素を置き換えたいy∗y∗\mathbf{y}^{*}常微分方程式系を数値的に積分するシミュレーションで使用する実際のパラメーターにます。この例のような1回限りのデータにテーブルを使用すると、過剰になり、必要以上にインクが多くなります。 図は簡単なケースだと思います：ドキュメントが（LaTeXソース、Markdown、RSTなどから）ビルドされるたびに、コードを実行してビルドプロセスを開始します。しかし、私のシミュレーションで生成された数値を私の論文と同期させるためのより良い提案があれば、ぜひ聞いてみてください。

34 software  documentation  reproducibility 

計算科学の研究では、再現性がますます重要になっています。（たとえば、科学の Roger Pengによるこの記事を参照してください。他のそのような記事やWebサイトも知っています。）しかし、どの程度の情報をジャーナル記事（またはオンライン）に含めるべきかはわかりません。私の計算研究は再現可能です（知的財産契約のような他の障害がないと仮定）。ガイドラインはありますか？もしそうでなければ、計算科学研究を再現可能にするために研究者がとるべきステップを提案できますか？ 回答で特に使用されるのは、これらの提案を実装するための可能な方法、つまりワークフローです。システムに依存しない、またはLinuxベースのワークフローが望ましいです。また、関連する個人的な経験について話し合うことも役立ちます。 私の特定のケースでは、MATLABで実行できるほど単純な2つの計算例を含む理論的な論文を書いています。この場合、MATLABスクリプトを含め、マシン上の特定のバージョンのMATLABを記録するだけで、再現性を確保できます。ただし、もっと複雑なシナリオが存在することは確かです。再現可能な研究を実行する方法についてのアドバイスは、将来のプロジェクトについて知るのに非常に役立ちます。

23 software  publications  documentation  reproducibility 

計算の再現可能な研究は、他の研究者が結果を生成するために必要なコードを他の研究者が利用できるようにすることを目的としています。カップルの論文は、私が使用上の社内自動微分パッケージ（と呼ばれる働いています：私は、私の研究の再現性のすべてをしたいのですが、私は思わぬ障害のビットに実行しているDAEPACKを（独自のライブラリに）CHEMKIN- II ;ライセンス条項は不明）。 これらのソフトウェアコンポーネントをオープンソースバージョンに置き換えるのは非常に時間がかかります。CHEMKIN-IIのオープンソースの代替物はCanteraと呼ばれますが、CanteraはC ++ですが、CHEMKIN-IIはFortran 77にあります。十分なCanteraコードを変更して自動処理できるようにするには、多大な労力が必要です。 C ++の差別化ツール。 これらの専用パッケージが必要な場合、研究者がCHEMKIN-IIにアクセスできないと仮定して、研究を可能な限り再現可能にする最良の方法は何ですか？DAEPACKはソースからソースへのトランスレーターなので、必ずしもDAEPACKを配布する必要はありません。出力を含めることができるかもしれません。これは、微分を計算するFortranソースファイルです。 より一般的には、あなたの作品にプロプライエタリなソフトウェアが必要であり、そのプロプライエタリなソフトウェアが広く利用できない場合（つまり、MATLAB、Mathematicaなどではない場合）、どのように仕事を再現可能にしますか？

19 software  publications  documentation  reproducibility 

ジャーナル数学ソフトウェア上のコンピューティング機械取引に関する協会（ACM TOMS）は、ソフトウェアの実装が含まれる数値計算アルゴリズムの多くの記事を掲載しています。彼らの編集方針によれば、アルゴリズム論文の提出には、その論文に記載されているアルゴリズムの実装のソースコードが含まれています。このソースコードは、ACMソフトウェア著作権およびライセンス契約の対象です。 私は自分の作品のソフトウェア実装をリリースすることに興味があるので、このライセンスの法的意味について心配しています。具体的には、このソフトウェアライセンスは一般的なオープンソースライセンス（GPLv3、BSD、MIT / X11、Apacheライセンスなど）とどのように相互作用しますか？

11 software  documentation 

Computational Physicsジャーナルの多くの出版物がコードのパフォーマンスにさまざまなメトリックを使用しているのを見てきました。特にGPGPUコードの場合、ユーザーが公開するタイミング結果には非常に多くの種類があるようです。特に、私は見ました： timeGPUとCPUのバージョンで（基本的に）実行し、平均を報告することの比較 呼び出された各GPU / CPU関数のプロファイリングデータの比較（そのため、実行されたmainすべての関数のタイミングを調整しますが、ドライバーの初期化時間は無視します） メモリ転送（この場合はPCI-Eバスを介して）、ディスクへのI / O、あるフォーマットから別のフォーマットへのデータ変換などを無視した、いくつかの関連機能のデータのプロファイリングの比較 1つの関数のみのプロファイリングデータの比較（たとえば、CPUとGPU量子モンテカルロでスピン更新を実行する時間のみを比較）、メモリ転送時間、ディスクへのI / O、ハミルトニアンの設定/対角化などを無視、など 2番目と3番目のメリットも確認​​できますが、最初のオプションは4つの中で最も「正直」です。言語間またはInfinibandとGigabit間のI / O実装の違いが4.99秒だった場合、5秒のランタイムの違いを報告するのは少しばかげています。最後のオプションは、この関数がプログラム全体の問題点でない限り、それについての情報を報告することは、私の結果を複製している誰かが見るパフォーマンスを反映しないだけなので、私には少し「不器用」に思えます。これらのアプローチのどれがより正直ですか？理想的には、紙にはこれらすべてが含まれますが、図/長さに制限がある場合、これは最も価値があり、正直で、提供に関連性がありますか？

8 performance  publications  documentation 

他の誰かがオープンソースコードを変更したり、独自のアプリケーション用に特定のものを開発する方法を見つけたりすると、私の仕事で役立つことがあります。ただし、すべてのソフトウェアに適切なドキュメントがあるわけではありません。 コードベースの全体的な構造を理解する良い方法は何ですか？ たとえば、どのルーチンがどのルーチンを呼び出すかなどです。この目的のためにDoxygenなどのドキュメントツールを自分で使用する可能性がありますが、もっと良い戦略があるかどうか疑問に思っていましたか？

8 software  documentation