คำถามติดแท็ก documentation

หลายครั้งที่ฉันได้รับสืบทอดหรือพบรหัสทางวิทยาศาสตร์ที่เขียนโดยคนอื่น ๆ (หรือบางครั้งแม้แต่งานของฉันเอง) ฉันสังเกตว่าเอกสารนั้นกระจัดกระจายหรือไม่มีเลย ถ้าฉันโชคดีฉันเห็นความคิดเห็นที่ให้ข้อมูล ถ้าฉันโชคดีมากมีความเห็นของ Doxygen และ Doxyfile เพื่อให้ฉันมีอินเทอร์เฟซของฟังก์ชั่นและ HTML ที่จัดรูปแบบเพื่อให้คำปรึกษา ถ้าฉันโชคดีมากมีคู่มือ PDF และตัวอย่างเพิ่มเติมจากความคิดเห็นของ Doxygen และซอร์สไฟล์และฉันดีใจเพราะมันทำให้ชีวิตของฉันง่ายขึ้นมาก ข้อมูลและเครื่องมือใดมีประโยชน์ในการทำเอกสารซอร์สโค้ด? สำหรับเรื่องนั้นข้อมูลและเครื่องมือใดที่มีประโยชน์ในการจัดทำเอกสารข้อมูลและผลลัพธ์ที่มาพร้อมกับซอร์สโค้ดนั้นในกรณีของซอฟต์แวร์ทางวิทยาศาสตร์

44 software  documentation 

ในหนึ่งในเอกสารของฉันฉันแสดงรายการผลลัพธ์ตัวเลขนอกเหนือจากตัวเลขบางอย่าง สิ่งที่ฉันต้องการจะทำคือตรวจสอบให้แน่ใจว่าผลลัพธ์ตัวเลขในเอกสารของฉันเห็นด้วยเสมอกับรหัส ตอนนี้ฉันเพิ่งคัดลอกผลลัพธ์เชิงตัวเลขจากผลลัพธ์การจำลองของฉันลงในกระดาษซึ่งง่ายมากและใช้เทคโนโลยีต่ำ แต่มีข้อผิดพลาดง่ายเพราะฉันสามารถคัดลอกผลลัพธ์ผิดพลาดหรือลืมซิงค์ผลลัพธ์กระดาษด้วย รหัสออก มีวิธีที่ดีในการเก็บผลลัพธ์ตัวเลขที่ฉันอ้างอิงในเอกสารของฉันให้สอดคล้องกับผลลัพธ์ที่สร้างโดยรหัสของฉันหรือไม่ (ที่นี่ฉันคิดว่าการใช้งานโค้ดนั้นทำได้ง่ายและใช้งานได้จริงทุกครั้งที่ฉันต้องการอัพเดทรายงาน) ผลลัพธ์เชิงตัวเลขเหล่านี้ไม่จำเป็นที่จะต้องยืมตัวไปเป็นแบบตาราง บางครั้งฉันมีตารางในต้นฉบับ แต่มากกว่าปกติผมได้พารามิเตอร์จำลองระบุว่าเป็นตัวเลขในสมการ ตัวอย่างจะเป็นสิ่งที่ชอบ: Y* * * *= ( y* * * *1, … , y* * * *n)y∗=(y1∗,…,yn∗)\begin{align} \mathbf{y}^{*} = (y_{1}^{*}, \ldots, y_{n}^{*}) \end{align} โดยที่ฉันต้องการแทนที่องค์ประกอบของเงื่อนไขเริ่มต้นด้วยพารามิเตอร์จริงที่ฉันใช้ในการจำลองที่ผสานระบบตัวเลขของสมการเชิงอนุพันธ์สามัญ การใช้ตารางสำหรับข้อมูลที่ใช้ครั้งเดียวเช่นตัวอย่างนี้ดูเหมือนว่ามากเกินไปและหมึกมากกว่าที่จำเป็นY* * * *y∗\mathbf{y}^{*} ฉันคิดว่าตัวเลขเป็นกรณีที่ง่ายกว่า: เมื่อใดก็ตามที่เอกสาร "สร้าง" (จากแหล่ง LaTeX, Markdown, RST ฯลฯ ) ให้เริ่มกระบวนการสร้างโดยการเรียกใช้รหัส อย่างไรก็ตามหากผู้คนมีข้อเสนอแนะที่ดีกว่าสำหรับการรักษาตัวเลขที่สร้างขึ้นโดยแบบจำลองของฉันในการซิงค์กับกระดาษของฉันฉันชอบที่จะได้ยินพวกเขา

34 software  documentation  reproducibility 

ความสามารถในการทำซ้ำมีความสำคัญมากขึ้นเรื่อย ๆ ในการวิจัยทางวิทยาศาสตร์คอมพิวเตอร์ (ตัวอย่างเช่นดูบทความนี้โดย Roger Peng in Science ; ฉันทราบถึงบทความและเว็บไซต์อื่น ๆ ด้วยเช่นกัน) อย่างไรก็ตามไม่ชัดเจนว่าฉันควรรวมข้อมูลจำนวนเท่าใดในบทความวารสาร (หรือออนไลน์) การวิจัยการคำนวณของฉันทำซ้ำได้ (สมมติว่าไม่มีอุปสรรคอื่น ๆ เช่นข้อตกลงด้านทรัพย์สินทางปัญญา) มีแนวทางใดบ้างหรือไม่หากผู้คนสามารถแนะนำขั้นตอนที่นักวิจัยควรทำเพื่อให้การวิจัยทางวิทยาศาสตร์การคำนวณของพวกเขาสามารถทำซ้ำได้? การใช้คำตอบโดยเฉพาะจะเป็นวิธีที่เป็นไปได้ในการใช้คำแนะนำเหล่านั้น - เวิร์กโฟลว์ เวิร์กโฟลว์ที่ไม่เชื่อเรื่องระบบหรือใช้ Linux เป็นที่ต้องการ นอกจากนี้การพูดคุยเกี่ยวกับประสบการณ์ส่วนตัวที่เกี่ยวข้องที่คุณมีก็จะเป็นประโยชน์เช่นกัน ในกรณีเฉพาะของฉันฉันกำลังเขียนบทความเชิงทฤษฎีพร้อมตัวอย่างการคำนวณสองอย่างที่ง่ายพอที่จะทำได้ใน MATLAB ฉันคิดว่าในกรณีนี้รวมถึงสคริปต์ 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