Questions tagged «documentation»

很多时候，当我继承或遇到其他人编写的科学代码（或偶而甚至是我自己的工作）时，我注意到文档稀疏或不存在。如果幸运的话，我会看到翔实的评论。如果我很幸运，甚至还有Doxygen注释和Doxyfile，这样我就可以使用函数接口和一些格式化的HTML进行查阅。如果我非常幸运，除了Doxygen和源文件注释之外，还有PDF手册和示例，我很欣喜，因为它使我的生活变得非常轻松。 哪些信息和工具可用于记录源代码？因此，对于科学软件，哪些信息和工具可用于记录与该源代码一起的数据和结果？

44 software  documentation 

在我的一篇论文中，我列出了一些数字结果以及一些数字。我想做的是确保论文中的数值结果始终与代码一致。现在，我只是将模拟结果的数值结果直接复制到纸张中，这非常简单且技术含量低，但容易出错，因为我可能会错误地复制结果，或者忘记将纸张结果与代码输出。 有没有一种很好的方法可以使我在论文中引用的数值结果与我的代码生成的结果保持同步？（在这里，我认为执行代码很容易且实用，只要我想更新论文即可。）这些数值结果不一定适合表格形式。有时，手稿中有表格，但更常见的是，我在方程式中将仿真参数列为数字。例如： y∗=(y∗1,…,y∗n)y∗=(y1∗,…,yn∗)\begin{align} \mathbf{y}^{*} = (y_{1}^{*}, \ldots, y_{n}^{*}) \end{align} 我想替换初始条件y ∗的元素y∗y∗\mathbf{y}^{*}用实际参数我在模拟中使用了实际参数，该模拟对常微分方程组进行了数值积分。使用一个表来处理一次性数据（例如本例）似乎是多余的，而且墨水过多。 我认为数字是一种更简单的情况：只要“构建”文档（从LaTeX源，Markdown，RST等），就可以通过执行代码来开始构建过程。但是，如果人们有更好的建议可以使模拟生成的图形与我的论文保持同步，那么我很乐意听到它们。

34 software  documentation  reproducibility 

可重复性在计算科学研究中变得越来越重要。（例如，请参见《科学》杂志的Roger Peng的这篇文章；我也知道其他此类文章和网站。）但是，我不清楚我应该在期刊文章（或在线文章）中包含多少信息来制作我的计算研究具有可重复性（假设没有其他障碍，例如知识产权协议）。是否有任何指南，如果没有，人们是否可以建议研究人员应采取哪些步骤来使他们的计算科学研究可重复？ 答案中特别有用的是实现这些建议的可能方法-从根本上说，工作流。最好是与系统无关或基于Linux的工作流。此外，讨论您所经历的任何相关个人经历也将有所帮助。 在我的特殊情况下，我正在写一篇理论论文，其中包含一些示例计算，这些计算很简单，可以在MATLAB中完成。我认为，在这种情况下，包括MATLAB脚本，并注意计算机上特定版本的MATLAB，足以确保可重复性。但是，我敢肯定还有更复杂的场景，有关如何进行可重复研究的建议对于将来的项目很有帮助。

23 software  publications  documentation  reproducibility 

可重复进行的计算研究旨在使计算论文中生成结果所需的代码可供其他研究人员使用，以便他们可以运行此代码以在该论文中复制结果。我想提出我的研究可重复的，但我快到有点障碍的：一对夫妇的论文，我就利用工作的内部自动分化包（称为DAEPACK一种专有库）（CHEMKIN- II；许可条款不清楚）。 用开源版本替换这些软件组件将非常耗时。已经存在CHEMKIN-II的开源替代品，名为Cantera，但Cantera使用C ++，而CHEMKIN-II使用Fortran77。这将需要大量的精力来修改足够的Cantera代码，以便可以自动处理它。 C ++的差异化工具。 鉴于我需要这些专有软件包，假设研究人员可能无法使用CHEMKIN-II，那么使我的研究尽可能可重复的最佳方法是什么？由于DAEPACK是一个源到源的翻译器，因此我不必分发DAEPACK。我也许可以包含其输出，该输出将是计算派生的Fortran源文件。 更一般而言，如果您在工作中需要专有软件，并且专有软件不广泛使用（例如，MATLAB，Mathematica等不是），那么如何使您的工作可再现？

19 software  publications  documentation  reproducibility 

该杂志对数学软件（TOMS ACM）计算机械协会事务上发布的数值算法，其中包括软件实现多篇。根据他们的编辑策略，提交算法论文包括该论文中描述的算法实现的源代码。此源代码受ACM软件版权和许可协议的约束。 由于我有兴趣发布自己作品的软件实现，因此我担心此许可证的法律含义。具体来说，该软件许可证如何与常见的开源许可证（例如GPLv3，BSD，MIT / X11和Apache许可证）交互？

11 software  documentation