एक पेपर के लिए कोड लिखने का सबसे उपयोगी तरीका क्या होगा ताकि पाठक उस कोड के परिणामों को स्पष्ट रूप से मेल कर सकें जो उन्हें उत्पन्न करता है?

Question

मैं एक प्रतिलिपि प्रस्तुत करने योग्य कागज लिख रहा हूं, और कागज में कम्प्यूटेशनल परिणाम हैं जो एक पायथन स्क्रिप्ट (एक समान MATLAB स्क्रिप्ट लगभग समान परिणाम उत्पन्न करता है) द्वारा उत्पन्न होते हैं। मुझे लगता है कि पेपर को पाठकों के लिए समझना आसान होगा यदि वे कोड में गणना के साथ पेपर में गणना से मेल खा सकते हैं। काम एक अमूर्त औपचारिकता का प्रस्ताव करता है, और कागज में उदाहरण इस औपचारिकता को पाठकों के लिए अधिक ठोस बनाने के लिए माना जाता है (जिनमें से कई इंजीनियर होंगे); कोड संभवतः गणना करने के तरीके का सबसे विस्तृत रिकॉर्ड होगा, और यह स्पष्ट कर सकता है कि समीक्षा प्रक्रिया के दौरान हमारी मदद कर सकता है।

क्या किसी के पास कोड और कम्प्यूटेशनल परिणाम (आंकड़े, समीकरण) के बीच पत्राचार को अधिक स्पष्ट करने के बारे में कोई सुझाव है?

उदाहरण के लिए, मैं सोच रहा था कि जब यह कागज में विभिन्न चरणों को लागू करने वाली कोड की पंक्तियों की बात आती है, तो मैं समीकरण संख्याओं का हवाला दे सकता हूं (यह अद्भुत होगा अगर मैं कोड और लाटेक्स के बीच संदर्भ को पार कर सकता हूं, लेकिन उन्हें हाथ से लेबल करना ठीक है) , और मैं विभिन्न उदाहरणों और आंकड़ों के अनुरूप कार्य लिख सकता हूं, जैसे कि

def example_1():
    # Insert code corresponding to first example
    pass

def figure_1():
    # Insert code that generates Figure 1
    pass

यदि कोड बड़े थे, और मैं यह समझाने की कोशिश नहीं कर रहा था कि इंजीनियरिंग में उपयोग किए जाने वाले विभिन्न गणितीय तरीकों का एक गुच्छा वास्तव में एक ही था, तो मैं शायद कोड को स्पष्ट करने के साथ इतना परेशान नहीं करूंगा, लेकिन सार प्रकृति को देखते हुए। कागज और छोटे कोड आधार, ऐसा लगता है जैसे इस अभ्यास में मूल्य हो सकता है।

Comments

आप Figshare पर कोड और आंकड़े दोनों पोस्ट कर सकते हैं । प्रत्येक को एक डीओआई जैसा पहचानकर्ता मिलेगा जिसे आप आवश्यक होने पर संदर्भित कर सकते हैं।

— डेविड केचेसन

सॉफ्टवेयर को निरंतर रखरखाव की आवश्यकता होती है। पत्रों को प्रकाशित किया जाता है और उस तिथि में उन्हें पत्थर में सेट किया जाता है। लक्ष्य सराहनीय है, लेकिन यह कभी काम नहीं करेगा। (मुझे गलत साबित होने में खुशी होगी: कोई भी व्यक्ति जो 5 वर्ष से अधिक पुराना एक पेपर पाता है, जिसका संबद्ध सॉफ़्टवेयर अभी भी काम करता है, मुझे कॉल कर सकता है। खुद के लिए, मुझे कभी भी किसी ऐसे पेपर से जुड़ा कोई कोड नहीं मिला है जो वास्तव में काम करता हो, इसके अलावा FFTW श्वेतपत्र की तरह "फ्रेमवर्क वर्णन पत्र"।)

— 13:14 पर user14717

Answer 1

1. आप नॉब में पूरा पेपर लिखने पर विचार कर सकते हैं । यह स्थापित करने के लिए थोड़ा थकाऊ है, लेकिन यह कोड और LaTeX- स्वरूपित पाठ, समीकरणों और आंकड़ों को मिलाने का एक बहुत शक्तिशाली तरीका है। लंबे कार्यक्रमों के लिए, यह एक लेख की तुलना में आपके कोड को एक पुस्तक से अधिक में बदल देता है, लेकिन छोटे कार्यक्रमों के लिए, यह बहुत अच्छी तरह से काम कर सकता है।

2. यदि आप उस दूर तक नहीं जाना चाहते हैं, तो यह अभी भी उचित रूप से सीधा होना चाहिए ताकि आपके कोड लिस्टिंग के टिप्पणी अनुभागों को फॉर्मेटएक्स का उपयोग करके प्रारूपित किया जा सके। listingsपैकेज आप इस हटा कर सकते हैं। यहाँ एक छोटा उदाहरण दिया गया है:

\ Documentclass {} लेख
\ Usepackage {} amsmath
\ Usepackage {} लिस्टिंग
\ Begin {document}
\ Begin {} समीकरण
  \ लेबल {eq: एक}
  Ax = b
\ अंत {} समीकरण
\ Begin {lstlisting} [escapechar = \%]
  # समीकरण% ~ \ eqref {eq: one}% के संदर्भ में टिप्पणी करें
  डी एफ (ए):
    लौटाना a + १
\ अंत {} lstlisting
\ अंत {document}

कुछ अतिरिक्त जोड़तोड़ के साथ, आपको समीकरण को सूचीबद्ध करने के लिए उपयोग किए जाने वाले मोनोस्पेस फ़ॉन्ट में प्रकट होने के लिए अपने संदर्भित समीकरण संख्या प्राप्त करने में सक्षम होना चाहिए।

Comments

Lstlisting वातावरण वास्तव में आपको एक प्रोग्रामिंग भाषा निर्दिष्ट करने की अनुमति देता है और यह अच्छी तरह से रंग कोड / शैली प्रत्येक भाषा के विभिन्न तत्वों को कोड करता है।

— वुल्फगैंग बंगर्थ

हाँ, मैं इसकी सुंदर छपाई का बहुत बड़ा प्रशंसक नहीं हूँ, लेकिन वोल्फगैंग सही है।

— बिल बार्थ

Answer 2

बिल द्वारा उल्लिखित नोएब एप्रोच काफी विकसित हो गया है, यह दोनों साक्षर प्रोग्रामिंग के तहत कोडिंग (वैज्ञानिक प्रकाशन के बजाय दस्तावेजीकरण) की मूल भावना है और अब कई स्वादों में आता है (मुझे लगता है कि अब शुरू में cweb का सामान्यीकरण था), जो doxygenऔर विभिन्न भाषा विशिष्ट संस्करण TeX, HTML और अन्य स्वरूपों में प्रलेखन उत्पन्न कर सकते हैं।

आपके बिंदु से अधिक, Noweb को कुछ समय के लिए Rसमुदाय में विकसित किया गया है (अच्छी तरह से मूल रूप से Sसमुदाय, इसलिए नाम) शीर्षक के तहत "स्वेव" एक "प्रतिलिपि प्रस्तुत करने योग्य अनुसंधान" पेपर प्रदान करने के लक्ष्य के साथ, जहां कोड वास्तव में चलाया जाता है लेटेक्स फ़ाइल संकलित है (और वैकल्पिक रूप से भी प्रदर्शित)। काफी सारे शैक्षिक पेपर स्वेव में लिखे गए हैं (सहित, मुझे विश्वास है, सभी आर-जर्नल के; लेकिन बायोसैटिस्टिक्स की पत्रिका भी देखें और यह प्रतिलिपि प्रस्तुत करने योग्य कागजों पर नीति है)।

जबकि स्वेव अभी भी किसी भी आधार आर इंस्टॉलेशन का हिस्सा है, इसे नाइट्र द्वारा प्रतिस्थापित किया जा रहा है जो अब भाषा अज्ञेय है , जो इसे आपके पायथन कोड के लिए संभव विकल्प बनाता है। नाइटर लाटेक्स या मार्कडाउन में लेखन का समर्थन करता है, सिंटैक्स हाइलाइटिंग, कैशिंग, स्रोत लेटेक्स से कोड का बाहरीकरण और इस तरह के काम के लिए कई अन्य वांछनीय विशेषताओं का समर्थन करता है।

पायथन के पास स्वयं के समाधान हैं जो समान हैं, ipython पुस्तिकाएं , जो HTML, शायद LaTeX को प्रस्तुत कर सकती हैं, लेकिन मुझे इस बारे में कम पता है।

एक अन्य परियोजना निश्चित रूप से देखने लायक है , एक अन्य भाषा-अज्ञेय कार्यक्रम है, जो लाटेक और एचटीएमएल के साथ बहुत अच्छी तरह से काम करता है। हालांकि यह वैज्ञानिक कागजात लिखने की तुलना में कोड के दस्तावेजीकरण में अधिक उदाहरण हैं, लाटेक्स में काम करते हुए इसे सीधे आगे होना चाहिए।

दोनों knitrऔर dexyitवास्तव में क्या करेंगे आप LaTeX में वर्णन है, बाहरी अजगर स्क्रिप्ट की ओर इशारा करते और कोड में पढ़ने सहित। डॉकबुक और एक्सएमएल में इसी तरह की चीजें पूरी की जा सकती हैं, हालांकि मैं इस दृष्टिकोण से कम परिचित हूं।

Answer 3

लाटेक्स पैकेज का खनन बहुत व्यापक सिंटैक्स हाइलाइटिंग प्रदान करता है (प्यूशंस के आधार पर) और दोनों दिशाओं में क्रॉस-रेफ़रिंग की अनुमति देता है। आप LaTeX से कोड भाग (मिंटेड पार्ट) के भीतर से बच सकते हैं और आप अपने मुख्य पाठ में कोड की पंक्तियों का उल्लेख कर सकते हैं। उसके शीर्ष पर, यह एक लिस्टिंग वातावरण प्रदान करता है ताकि आप "सूची की सूची" (तालिकाओं की सूची की तरह) उत्पन्न कर सकें और संपूर्ण लिस्टिंग को संदर्भित करने की अनुमति दे सकें। नीचे LaTeX MWE और इसके आउटपुट LuaLaTeX के साथ देखें (कोड को जज न करें :-))।

एक अन्य विकल्प एक ही लेखक / अनुचर से PythonTeX का उपयोग करना होगा जो LaTeX स्रोत को संकलित करते समय गणना चलाने की अनुमति देता है, इसलिए कागज और कोड परिणाम हमेशा एक साथ उत्पन्न होते हैं और इसलिए हमेशा सुसंगत होते हैं। यहां PythonTeX गैलरी देखें ।

\documentclass[a4paper,notitlepage,11pt]{article}

\usepackage{amsmath}
\usepackage{cases}
\usepackage{minted}

\begin{document}

The mathematical definition of the Fibonacci
series is given in~Equations~(\ref{eq:fibdef:init1}--\ref{eq:fibdef:rule})
It can be implemented using either a recursive or iterative algorithm
in Python.

\begin{numcases}{f(n)=}
  \label{eq:fibdef}
    0               & n = 0 \label{eq:fibdef:init1}\\
    1               & n = 1 \label{eq:fibdef:init2}\\
    f(n-1) + f(n-2) & \text{otherwise} \label{eq:fibdef:rule}
\end{numcases}

The algorithms below are an implementation of both variants.
Listing~\ref{alg:fib_recursive} shows the recursive variant (see
line~\ref{alg:fibo_rec:line_rec} in listing~\ref{alg:fib_recursive}) while
listing~\ref{alg:fib_iterative} shows the iterative variant. Both can be
optimized, of course.

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_rec(N):
    if N == 0:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init1})]|
    elif N == 1:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init2})]|
    else:
        result = fibo_rec(N-1) + fibo_rec(N-2) |\label{alg:fibo_rec:line_rec}[Comment: See case (\ref{eq:fibdef:rule})]|

    return result
  \end{minted}
\caption{Fibonacci recursive}
\label{alg:fib_recursive}
\end{listing}

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_iter(N):
    if N == 0:
        fib_N = 1
    elif N == 1:
        fib_N = 1
    else:
        fib_Nmin2 = 1
        fib_Nmin1 = 1
        for i in range(2,N+1):
            fib_N = fib_Nmin2 + fib_Nmin1
            fib_Nmin2 = fib_Nmin1
            fib_Nmin1 = fib_N
    return fib_N
  \end{minted}
\caption{Fibonacci iterative}
\label{alg:fib_iterative}
\end{listing}

\end{document}

Answer 4

ऑर्ग-मोड के लिटरेट प्रोग्रामिंग फंक्शनलिटी का उपयोग करें ।

अधिकांश ऑर्ग-मोड उपयोगकर्ता विशेष रूप से अंतर्निहित परियोजना / समय प्रबंधन कार्यक्षमता या कई लोकप्रिय फ़ाइल स्वरूपों में दस्तावेज़ों को निर्यात करने की क्षमता पर ध्यान केंद्रित करते हैं, जैसे पीडीएफ , पाठ फ़ाइलों को बनाए रखने के लिए आसान से ।

हालांकि, ओआरजी-मोड की सबसे अच्छी विशेषता 30 से अधिक भाषाओं में साक्षर कार्यक्रम बनाने की क्षमता है, जो ओपन सोर्स समुदाय द्वारा हर महीने जोड़े जाने वाली अधिक भाषाओं के साथ है।

रूबी और पायथन का उपयोग कर नीचे दिए गए तुच्छ कोड उदाहरण हैं:

 #+NAME: trivial-code-ex1
 #+BEGIN_SRC ruby 
   "hello world!"
 #+END_SRC

 #+RESULTS: trivial-code-ex1
 : hello world!


 #+NAME: func-of-x-and-y
 #+BEGIN_SRC python :var x=1 :var y=2 :session
   x + y
 #+END_SRC

 #+RESULTS: func-of-x-and-y
 : 3

पेशेवरों

• आर, पायथन, रूबी, पर्ल, सी, सी ++, जावा, क्लोजर, जावास्क्रिप्ट, कॉमन लिस्प, शेल, एसक्यूएल, सहित 30 से अधिक प्रोग्रामिंग भाषाओं के लिए समर्थन ...

• की योग्यता:

  • SRCब्लॉक परिणाम को आउटपुट और / या मान के रूप में कैप्चर करें ।
  • SRCकोड, सूचियों, तालिका, लेटेक्स, एचटीएमएल के रूप में प्रारूप ब्लॉक परिणाम
  • SRCब्लॉक के चर के लिए बाहरी और आंतरिक दोनों डेटा का उपयोग करें ।
  • वैरिएबल के रूप SRCमें नामित ब्लॉकों के आउटपुट का उपयोग SRCब्लॉकों में करें।
  • ब्लॉक के nowebअंदर सिंटैक्स का उपयोग करें SRC।

    प्रो टिप: आप nowebसिंटैक्स का उपयोग कर सकते हैं :

    • किसी अन्य ब्लॉक के अंदर SRC, एक नामित ब्लॉक से कोड डालें ।func-of-x-and-ySRC

      #+BEGIN_SRC python :session :noweb yes 
        x=2
        y=3
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f({0},{1}) equals\n\n {2}".format(x,y,<<func-of-x-and-y>>)
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(2,3) equals
      : 
      :  5

    • नामांकित SRCब्लॉक के परिणाम डालें , उदाहरण func-of-x-and-yके लिए किसी अन्य SRCब्लॉक के अंदर

      #+BEGIN_SRC python :session :noweb yes 
        "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f(3,4) equals\n\n <<func-of-x-and-y(x=3,y=4)>>"
      #+END_SRC
      
      #+RESULTS:
      : f(x,y) is
      : 
      :  x + y 
      : 
      : so f(3,4) equals
      : 
      :  7

    • SRCपठनीयता के लिए ऑर्ग-मोड फ़ाइल में कहीं भी नामित ब्लॉक रखें और :tangleहेडर या एक्सपोर्ट कोड को बाहरी स्रोत फ़ाइलों में उपयोग करें।

• ओपन सोर्स प्रोजेक्ट - बीयर में दोनों फ्री और फ्री में फ्री।

• टेक्स्ट फाइल फॉर्मेट, git जैसे वर्जन कंट्रोल सॉफ्टवेयर के साथ बढ़िया काम करता है।
• अन्य विशेषताओं के ओडल्स जो मैं इसमें नहीं जाऊंगा क्योंकि यह उत्तर लंबा हो रहा है।

विपक्ष

• ऑर्ग-मोड का उपयोग करने के लिए ग्नू इमैक को स्थापित और कॉन्फ़िगर करना होगा।

  नोट: आप में से अधिकांश ने इस उत्तर को पढ़ना बंद कर दिया था जब आप ग्नू ईमेक पढ़ रहे थे। जो बहादुर आत्माएं बची हैं, उनके लिए आप अपने पसंदीदा टेक्स्ट एडिटर का उपयोग कर सकते हैं और कमांड-लाइन से अपनी ऑर्ग-मोड फ़ाइलों को संसाधित करने के लिए बस एमएसीएस कॉल कर सकते हैं।

• आपके द्वारा आवश्यक सभी प्रोग्रामिंग सॉफ़्टवेयर को स्थापित और कॉन्फ़िगर करने की आवश्यकता है।

• यदि आप PDF बनाना चाहते हैं तो LaTeX उपयोगिताओं को स्थापित और कॉन्फ़िगर करने की आवश्यकता है।
• org- मोड के रूप में अच्छी तरह से पता नहीं है ipython notebooksया Sweaveतो आप शायद के रूप में कई नौकरी पोस्टिंग नहीं देखेंगे, भले ही साक्षर प्रोग्रामिंग कार्यक्षमता 2008 में जोड़ा गया था।
• लर्निंग ऑर्ग-मोड मार्कअप सिंटैक्स
• यदि संभव हो तो सीखें कि ग्नू ईमेक या स्पेसमैक्स का उपयोग कैसे करना है, तो ऑर्ग-मोड के साथ काम करने वाले अन्य कूल टूल्स को बाहर निकालना चाहते हैं।

---

पूर्ण प्रकटीकरण: मैं एटम संपादक के लिए ऑर्ग-मोड पैकेज का प्राथमिक अनुचर हूं ।

---

इस उत्तर में कोड का उपयोग करके मान्य किया गया था:
emacs संस्करण: GNU Emacs 25.2.1
org-mode संस्करण: 9.1.2