-
Notifications
You must be signed in to change notification settings - Fork 10
/
Copy pathhow-to-write-paper.tex
1857 lines (1452 loc) · 115 KB
/
how-to-write-paper.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[authoryear,12pta4paper,fleqn]{article}
% \usepackage[paper=a4paper,top=1.5cm,left=1.2cm,right=0.8cm,
% foot=1cm,bottom=1.5cm]{geometry}
\usepackage{arxiv} %ss https://www.overleaf.com/gallery/tagged/arxiv
\usepackage[utf8]{inputenc} % utf8 support %!!!!!!!!!!!!!!!!!!!!
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb, amsthm,mathtools,mathrsfs,stmaryrd,titletoc}
\usepackage{natbib} % bibtex
% need to install mtpro2
\let\Bbbk\relax
%\usepackage[subscriptcorrection,slantedGreek,nofontinfo,mtphrd]{mtpro2}
\usepackage[retainorgcmds]{IEEEtrantools}
\usepackage[usenames]{color}
\usepackage{tabularx}
\usepackage{booktabs}
\usepackage[font=small,labelfont=md]{caption,subfig}
\usepackage{multirow}
\usepackage[bookmarks=true,colorlinks=true,linkcolor=blue,citecolor=red,backref=page]{hyperref}
\usepackage{float} % make new float environment such as boxes (captioned)
\usepackage{listings} % insert source code
\usepackage{algorithm}
%\usepackage{algorithmicx}
\usepackage{algpseudocode}
\usepackage[most]{tcolorbox}
\usepackage{IEEEtrantools}
%\usepackage[ruled,vlined]{algorithm2e}
%\sloppy
%\usepackage{authblk}
% nomenclature and glossaries for XFEM, CDM
%\usepackage{nomencl}
\usepackage[acronym]{glossaries}
% the following packages just to improve the latex experience
%\usepackage{silence} %
\usepackage{silence}
\WarningsOff
\usepackage{siunitx}
\usepackage[norefs,nocites,ignoreunlbld]{refcheck} % warning for unreferred figs/tables/equas
% search in the .log file for unused fig to detect figures not referred to in the text.
% activate={true,nocompatibility} - activate protrusion and expansion
% final - enable microtype; use "draft" to disable
% tracking=true, kerning=true, spacing=true - activate these techniques
% factor=1100 - add 10% to the protrusion amount (default is 1000)
% stretch=10, shrink=10 - reduce stretchability/shrinkability (default is 20/20)
\usepackage[capitalise]{cleveref} %Basically, cleveref must be loaded last.
% clever ref: instead of Fig.~\ref{d}, use \cref{d} or \Cref{d} capitalise -> Figure 1
% \crefrange{eq1}{eq5}
\usepackage[textsize=tiny]{todonotes}
\usepackage{nicefrac} % type inline fractions: \nicefrac{1}{2}
\usepackage{setspace} % gives commands such as \doublespacing, or \begin{singlespace} \end{singlespace}
\usepackage{lineno} % write numbers for lines
%\usepackage[mediumspace,mediumqspace,Grey,squaren]{SIunits}
%\usepackage{totcount} % to count the total number of references and other things
%\usepackage[figure,table]{totalcount}
\usepackage{blkarray, bigstrut} % write complicated matrices with borders, see http://mirror.lagoon.nc/pub/ctan/macros/latex/contrib/blkarray/blkarray.pdf
\usepackage{tikz}
\usetikzlibrary{arrows,decorations.pathmorphing,decorations.pathreplacing,backgrounds,positioning,fit,matrix,math,shapes.misc}
\tikzset{cross/.style={cross out, draw=black, minimum size=2*(#1-\pgflinewidth), inner sep=0pt, outer sep=0pt}, cross/.default={1pt}}
\usepackage{wasysym}
\usepackage{gensymb} % for degree symbol
\usepackage{pgfplots}
\pgfplotsset{compat=newest}
%% the following commands are needed for some matlab2tikz features
\usetikzlibrary{plotmarks}
\usetikzlibrary{arrows.meta}
\usepgfplotslibrary{patchplots}
\usepackage{grffile} % load graphicx package, The package extends the file name processing of package graphics to sup- port a larger range of file names.
\usepackage{pgf}
%\usepackage{underscore}
\usepackage[english]{babel} %also automatically activates the appropriate hyphenation rules for the language you choose
\usepackage[title,titletoc,toc]{appendix}
%\usepackage[referable]{threeparttablex}
\usepackage{threeparttable}
\usepackage{xspace}
\usepackage[scaled=0.84]{beramono}
%\usepackage[breakwithin,symbol]{parnotes} % foonote in tables, but not good looking
%%%% these patches ensure that the backrefs point to the actual occurrences of the citations in the text, not just the page or section in which they appeared
%%%% https://tex.stackexchange.com/questions/54541/precise-back-reference-target-with-hyperref-and-backref
%%%% BEGIN BACKREF DIRECT PATCH, apply these AFTER loading hyperref package with appropriate backref option
% The following options are provided for the patch, currently with a poor interface!
% * If there are multiple cites on the same (page|section) (depending on backref mode),
% should we show only the first one or should we show them all?
\newif\ifbackrefshowonlyfirst
\backrefshowonlyfirstfalse
%\backrefshowonlyfirsttrue
%%%% end of options
%
% hyperref is essential for this patch to make any sense, so it is not unreasonable to request it be loaded before applying the patch
\makeatletter
% 1. insert a phantomsection before every cite, so hyperref has something to target
% * in case natbib is loaded. hyperref provides an appropriate hook so this should be safe, and we don't even need to check if natbib is loaded!
\let\BR@direct@old@hyper@natlinkstart\hyper@natlinkstart
\renewcommand*{\hyper@natlinkstart}{\phantomsection\BR@direct@old@hyper@natlinkstart}% note that the anchor will appear after any brackets at the start of the citation, but that's not really a big issue?
% * if natbib isn't used, backref lets \@citex to \BR@citex during \AtBeginDocument
% so just patch \BR@citex
\let\BR@direct@oldBR@citex\BR@citex
\renewcommand*{\BR@citex}{\phantomsection\BR@direct@oldBR@citex}%
% 2. if using page numbers, show the page number but still hyperlink to the phantomsection instead of just the page!
\long\def\hyper@page@BR@direct@ref#1#2#3{\hyperlink{#3}{#1}}
% check which package option the user loaded (pages (hyperpageref) or sections (hyperref)?)
\ifx\backrefxxx\hyper@page@backref
% they wanted pages! make sure they get our re-definition
\let\backrefxxx\hyper@page@BR@direct@ref
\ifbackrefshowonlyfirst
%\let\backrefxxxdupe\hyper@page@backref% test only the page number
\newcommand*{\backrefxxxdupe}[3]{#1}% test only the page number
\fi
\else
\ifbackrefshowonlyfirst
\newcommand*{\backrefxxxdupe}[3]{#2}% test only the section name
\fi
\fi
% 3. now make sure that even if there is no numbered section, the hyperref's still work instead of going to the start of the document!
\RequirePackage{etoolbox}
\patchcmd{\Hy@backout}{Doc-Start}{\@currentHref}{}{\errmessage{I can't seem to patch backref}}
\makeatother
%%%% END BACKREF PATCHES
% user-defined macros to save time
\newcommand{\bfsigma}{\boldsymbol{\sigma}}
\newcommand{\bfepsilon}{\boldsymbol{\epsilon}}
\newcommand{\bfu}{\boldsymbol{u}}
\newcommand{\bfx}{\boldsymbol{x}}
\newcommand{\bfphi}{\boldsymbol{\phi}}
\newcommand{\bftheta}{\boldsymbol{\theta}}
\newcommand{\te}{\text{e}}
\newcommand{\td}{\text{d}}
\newcommand{\tp}{\text{p}}
%-----------------------------------------------------------------------
\newcommand{\tty}[1]{\textnormal{\texttt{#1}}}
\newcommand{\sym}[1]{\textnormal{\textit{#1}}}
\newcommand{\eg}{\textit{e.g.}\xspace}
\newcommand{\ie}{\textit{i.e.},\xspace}
\newcommand{\etc}{\textit{etc.}\@\xspace}
\newcommand{\vm}[1]{\mathbf{#1}}
\newcommand{\trans}{^\mathrm{T}}
\newcommand{\bsym}[1]{\boldsymbol{#1}}
% \renewlist{tablenotes}{enumerate}{1}
% \makeatletter
% \setlist[tablenotes]{label=\tnote{\alph*},ref=\alph*,itemsep=\z@,topsep=\z@skip,partopsep=\z@skip,parsep=\z@,itemindent=\z@,labelindent=\tabcolsep,labelsep=.2em,leftmargin=*,align=left,before={\footnotesize}}
% \makeatother
\crefname{appsec}{Appendix}{Appendices}
%\input{pre_commands.tex}
% write numbers for lines
% comment out for final pdf
%\linenumbers
% cleverref package
\crefname{figure}{Fig.}{Figs.}
\crefname{equation}{Equation}{Equations}
% todonotes on the left margin
\reversemarginpar
%\setlength{\oddsidemargin}{3mm}
%\setlength{\evensidemargin}{-3mm}
%\setlength{\textwidth}{160mm}
%\setlength{\textheight}{220mm}
\renewcommand*{\backref}[1]{}
\renewcommand*{\backrefalt}[4]{[{%
\ifcase #1 %
\or Cited on page~#2%
\else Cited on pages #2%
\fi%
}]}
%\floatstyle{ruled}
%\newfloat{Fbox}{thp}{lop}[chapter]
%\floatname{Fbox}{Box}
%
%\theoremstyle{remark}
%\newtheorem{thm}{Theorem}[chapter]
%\newtheorem{rmk}[thm]{Remark}
%% code listing
\lstloadlanguages{C++,Matlab,Python}
\definecolor{mygreen}{rgb}{0,0.6,0}
\definecolor{darkgray}{rgb}{0.95,0.95,0.95}
\definecolor{myblue}{rgb}{0.01, 0.31, 0.59}
\lstset{backgroundcolor=\color{darkgray},
basicstyle=\color{red}\ttfamily,
keywordstyle=\color{blue}\bfseries
}
\lstdefinestyle{C++}
{
basicstyle=\footnotesize, numbers=none, numberstyle=\tiny,%
showstringspaces=false, language=C++, escapechar=|,frame=tb,
commentstyle=\color{mygreen}
}
\lstdefinestyle{python}
{
basicstyle=\scriptsize, numbers=left, numberstyle=\tiny,%
showstringspaces=false, language=Python, escapechar=|,frame=tb,%
commentstyle=\color{mygreen},
morekeywords={inner, Function, TrialFunction, TestFunction, solve, FunctionSpace,VectorFunctionSpace,grad,
LinearVariationalProblem, LinearVariationalSolver, dx,UnitSquareMesh, lhs, rhs, sym, method, region, dimension,run, solid, ulmpm, tlmpm,linear,cylinder,block,material,fix, group,set_dt,dump,run_time,NULL,initial_velocity_particles,sphere,damage_johnson_cook,shock,johnson_cook,velocity_nodes,x,y,z,T,vx,eos,strength,damage,s11}
}
\newtcolorbox[auto counter,crefname={Box}{Boxes}]{MyBox}[2][]{%
colback=gray!5!white,colframe=red!75!black,fonttitle=\bfseries,before skip=20pt plus
2pt,after skip=20pt,
title=Box~\thetcbcounter: #2, #1}
\lstdefinestyle{commentstyle}{color=\color{green}}
\lstdefinestyle{C-numbered}
{
basicstyle=\footnotesize, numbers=left, numberstyle=\tiny,%
showstringspaces=false, language=C++, escapechar=|,frame=tb,
commentstyle=\color{mygreen}
}
\lstdefinestyle{latex}
{
basicstyle=\footnotesize, numbers=left, numberstyle=\tiny,%
showstringspaces=false, language=[LaTeX]TeX, escapechar=|,frame=tb,%
commentstyle=\color{mygreen},
morekeywords={cell, ones, repmat, intersect, unique,includegraphics,input,toprule,midrule,bottomrule,colorbox,table,tabularx,setlength,subfloat,figure,width,subplots,set_xlabel,set_ylabel,set_ylim,set_xlim,legend,plot,update,savefig,lstloadlanguages,definecolor,lstset,tableofcontents,boldsymbol,draw,node,tikzpicture,circle,equation,array,varOmega,mathscr,text,maketitle,keywords,crefname}
}
\lstdefinestyle{C-numbered}
{
basicstyle=\footnotesize\ttfamily, numbers=left, numberstyle=\tiny,%
showstringspaces=false, language=C++, escapechar=|,frame=tb,
keywordstyle=\color{myblue}\bfseries,
keywordstyle=[2]{\color{red}\bfseries},
commentstyle=\color{blue}\textit, stringstyle=\color{cyan}\ttfamily,numbersep=5pt,
morekeywords=[2]{getElements,XTable,TABLE,idx_t,TABLE_NAME,TABLE_WEIGHTS,GET_TABLE,ref,getNodes,ElemGroup,ElemSet,NodeSet,Assignable,Properties,IdxVector,getIndices,size,Vector,Cubix,Matrix,Ref,IShape,newInstance,IShapeFactory,Model,Module,getDofIndices,select,addBlock,getElemNodes,StateVector,pushBack,run,ChainModule,get,getOld,addType,addDofs,getUniqueNodesOf,XDofSpace,getData,getProps,makeProps,maxOf,set,get,getShapeGradients,MatrixBuilder,String,getSomeCoords,matmul,transpose,findType,resize,ActionParams,MATRIX0,INT_VECTOR,Actions::GET_MATRIX0,Actions::GET_MATRIX2,Object,InputModule,InitModule,InfoModule,NonlinModule,FemViewModule,getShapeFunctions,ipointCount,nodeCount,addConstraint,Actions,GET_MATRIX2,GET_MATRIX0,jive,BEGIN, joinNames, END,slice,GET_INT_VECTOR,ModelFactory,models, modules,Array,input,init,extraModules,log,view,declare, model, Flex,STATE0,STATE1,STATE2,solver,precision,jem,base,System,out}
}
\lstnewenvironment{code-c-num}[1][]%
{
\noindent
\minipage{\linewidth}
\vspace{0.5\baselineskip}
\lstset{style=C-numbered, xleftmargin=5mm, gobble=4, #1,belowskip=.5cm,}
}
{\endminipage}
\lstnewenvironment{snippet}[1][]
{
\lstset{style=python, xleftmargin=5mm, gobble=4, #1}
}
{}
\lstnewenvironment{snippetlatex}[1][]
{
\lstset{style=latex, xleftmargin=5mm, gobble=4, #1,tabsize=3}
}
{}
%%
\newcolumntype{C}{>{\centering\arraybackslash}X}
\newcolumntype{b}{X}
\newcolumntype{s}{>{\hsize=0.5\hsize}X}
\newcolumntype{L}{>{\raggedright\arraybackslash}X}
\newcolumntype{R}{>{\raggedleft\arraybackslash}X}
\flushbottom
\definecolor{Sun}{rgb}{0.164,0.126,0.322}
\definecolor{Green}{rgb}{0,0.300,0.300}
\definecolor{Red}{rgb}{0.4,0,0}
\definecolor{Grey}{RGB}{105,105,105}
\definecolor{White}{rgb}{1,1,1}
%\newcommand\Algphase[1]{%
% \vspace*{-.7\baselineskip}\Statex\hspace*{\dimexpr-\algorithmicindent-2pt\relax}%\rule{\textwidth}{0.4pt}%
% \Statex\hspace*{-\algorithmicindent}\textbf{#1}%
% \vspace*{-.7\baselineskip}\Statex\hspace*{\dimexpr-\algorithmicindent-2pt\relax}%\rule{\textwidth}{0.4pt}%
%}
% for blocks in Algorithm
\algblockdefx{Start}{End}[1]{\textbf{#1}}{\textbf{end}}
%without this, xelatex would not work with fontspec
\DeclareTextCommand{\nobreakspace}{T1}{\leavevmode\nobreak\ }
%%% vertical rules in cyan color
%\makeatletter
%\renewcommand{\algocf@Vline}[1]{% no vskip in between boxes but a strut to separate them,
% \strut\par\nointerlineskip% then interblock space stay the same whatever is inside it
% \algocf@push{\skiprule}% move to the right before the vertical rule
% \hbox{\bgroup\color{cyan}\vrule\egroup%
% \vtop{\algocf@push{\skiptext}%move the right after the rule
% \vtop{\algocf@addskiptotal #1}\bgroup\color{cyan}\Hlne\egroup}}\vskip\skiphlne% inside the block
% \algocf@pop{\skiprule}%\algocf@subskiptotal% restore indentation
% \nointerlineskip}% no vskip after
\newcommand{\latex}{\LaTeX\xspace}
\numberwithin{equation}{section}
%\graphicspath{{./figures/}}
\newcommand\Lang[1]{\textsc{#1}}
\theoremstyle{remark}
%\newtheorem{thm}{Theorem}[section]
%\newtheorem{rmk}[thm]{Remark}
\newtheorem{rmk}{Remark}
% total number of references
%1. bibtex
% total number of references
% \newtotcounter{citenum}
% \def\oldcite{}
% \let\oldcite=\bibcite
% \def\bibcite{\stepcounter{citenum}\oldcite}
% new command for colorbox gray
\newcommand{\graybox}[1]{%
\begingroup\setlength{\fboxsep}{1pt}%
\colorbox{darkgray}{\texttt{\hspace*{2pt}\vphantom{Ay}#1\hspace*{2pt}}}%
\endgroup
}
%\journal{Advances in Engineering Software}
%\journal{International Journal for Numerical Method in Engineering}
%\newcommand\barbelow[1]{\stackunder[1.2pt]{$#1$}{\rule{.8ex}{.075ex}}}
%\begin{frontmatter}
%\title{Modeling crack propagation of concrete gravity dams with the phase-field regularized cohesive zone model}
\title{\textbf{How to effortlessly write a high quality scientific paper in the field of computational engineering and sciences }}
%\tnotet%ext[label1]{Dedicate to }
% use optional labels to link authors explicitly to addresses:
% \author[label1,label2]{}
% \address[label1]{}
% \address[label2]{}
% \author[1]{Vinh Phu Nguyen\corref{cor1}}
% \ead{phu.nguyen@monash.edu}
% \author[2]{Stephane Bordas}
% \author[3]{Alban de Vaucorbeil}
% \cortext[cor1]{Corresponding Author}
% \address[1]{Department of Civil Engineering, Monash University, Clayton 3800, VIC, Australia}
% \address[2]{Institute of Computational Engineering, University of Luxembourg, Faculty of Sciences Communication and Technology, Luxembourg}
% \address[3]{Institute for Frontier Materials, Deakin University, Geelong, VIC, 3216, Australia}
%\maketitle
%\author{Vinh Phu Nguyen\thanks{corresponding author} and St\'ephane Bordas and Alban de Vaucorbeil}
\author{
Vinh Phu Nguyen\thanks{corresponding author} \\
Department of Civil Engineering\\
Monash University\\
Clayton 3800, VIC, Australia\\
\texttt{phu.nguyen@monash.edu} \\
%% examples of more authors
\And
St\'{e}phane Bordas \\
Institute of Computational Engineering\\
University of Luxembourg\\
Luxembourg\\
\texttt{stephane.bordas@uni.lu}
\And
Alban de Vaucorbeil\\
Institute for Frontier Materials\\
Deakin University\\
Geelong, VIC, 3216, Australia\\
\texttt{alban.devaucorbeil@deakin.edu.au}
}
\renewcommand{\shorttitle}{How to write a high quality scientific paper}
\begin{document}
\maketitle
\begin{abstract}
Writing a good scientific paper is not easy for many graduate students. To help these students, particularly those working on the field of computational engineering and sciences, this paper presents some writing guidelines that we have collected and used for the last twenty years. The guidelines consist of three major parts. The first part is a writing framework that helps us to have a nearly complete paper when the last analysis task has been finished. The key ideas of this framework are: (1) writing should start early in the research project, (2) research and writing are carried out simultaneously, and (3) best tools for writing should be used. The second part is about how to write the major components of a paper from title, abstract, introduction, results to conclusion and references. The writing is based on the writing style that writing is to inform not to impress and writing is for reader and not for authors. And finally, the third part is technical: we present \LaTeX\ centered writing tools--due to our personal preferences--and \LaTeX\ techniques to prepare high-quality images, tables, algorithms and source codes.
\end{abstract}
% *********************************************************************************************************
% The process seems working well as it has helped us writing thousands of pages without feeling a pain. We hope it works for you too.
\keywords{
scientific writing \and \LaTeX \and scientific publication \and high quality writing \and reproducibility.
}
%\end{frontmatter}
\tableofcontents
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
%\showthe\textwidth % => width of the pdf, see in log file, is 468 pt. use it in plot.py for great plots.
Publishing original research in a peer-reviewed journal is an important parameter to assess academic achievements. To get your paper published, not only its findings should be significant but it should also be well written such that these findings can be efficiently transmitted throughout the scientific community. The value of writing well should not be underestimated for many reasons, indirectly and directly beneficial to the authors. Firstly, writing well leverages your work since 60\% of reviewers criticisms pertain to the quality of the writing or tables and graphs with only about 40\% to the quality of the scientific work \citep{iles1997guidebook}. Secondly, a research paper is designed to create new knowledge and communicate it to the community \citep{gopen1990science}, but if you can't communicate that knowledge (because the paper is not well written) to the reader effectively, you have accomplished nothing: no new knowledge. Thirdly, well written papers likely get more citations \citep{RePEc:nas}.
It should be clear now that writing skills are vital to the career of a researcher. Unfortunately, she/he does not usually get trained on writing. Furthermore, researchers most often do not pay attention to this because they have to focus on their research. And why they have to care if (many of) their papers get published and cited? We used to be in the same situation.
What they do not know (or do not care about?) is that there are, probably, many readers struggling to grasp their papers. The situation might be worse as Judy Swan -- the Associate Director for Writing in Science and Engineering at Princeton University -- saw it: ``scientific writing is bad writing''. Or as a paper published in Nature Index concluded ``Science is getting harder to read''\footnote{\url{https://www.natureindex.com/news-blog/science-research-papers-getting-harder-to-read-acronyms-jargon}.}.
To improve the scientific writing, books and articles giving advice on how to write clear papers have been written \citep{strunk2007elements,day1998write,ashby2000write,plaxco2010art,gewin2018write}. Building on the advice found in these works and our total 20 years of experiences, this brief paper gives guidance in writing high quality research papers. By high quality papers, we mean those of which scientific findings are not buried under a poorly written text. The paper is centered around three parts.
The first part is a writing framework that helps us to have a nearly complete paper when the last analysis task has been finished. The key ideas of this framework are: (1) writing should start early in the research project, (2) research and writing are carried out simultaneously, and (3) best tools for writing should be used. The second part is about how to write the major components of a paper; they include title, abstract, introduction, results, conclusion and references. The principle that guides our writing is: writing is to inform, and not to impress and writing is for reader and not for authors. And finally, the third part is technical: we present \LaTeX\ centered writing tools--based on our personal preferences--and \LaTeX\ techniques to prepare high-quality images, tables, algorithms and source codes. Due to our background in computational mechanics -- a sub-branch of computational engineering and sciences-- we have used, as a model, a typical computational mechanics project: one develops a new model, implements it in a code, and carries out simulations using that code to demonstrate the performance of the model.
There is no single, correct way to write. Our goal was not to convince you that what is described in this paper is the one true way, but instead to get people thinking, talking and sharing ideas about writing. It is obvious that, no matter how good you are as a writer, a bad research idea will not result in a good paper. Therefore, we assume that you have had a sound research idea. The suggestions presented in this paper should then help you to have a nearly complete paper when the last analysis task has been complete and the paper, once get published, will surely well communicate its selling points to the community.
The remaining of the paper is structured as follows. First, in \cref{sec:tools}, our favorite writing tools are presented. These tools are mostly open source and cross platform. Then, \cref{sec:writing-tips} provides actionable suggestions on how to write a good paper. Particularly, we present an iterative writing process that is intertwined with your research.
As we use \LaTeX--a high-quality free typesetting system--we present some \LaTeX\ related guidelines on how to prepare high-quality vector images, good-looking tables, algorithms, source codes and tweaks for two-column format papers (see \cref{sec:latex}).
Finally, with the pressure to “publish” (or perish), it is increasingly difficult for students and researchers alike to resist the temptation to submit a “large” number of papers. Some of these papers might not be ready for submission yet. We present some considerations regarding this issue (\cref{sec:submission}).
%The \LaTeX\ source of this paper and various \texttt{Python} scripts used to prepare high quality images can be found at the github account of the first author: \url{https://github.com/vinhphunguyen/how-to-write-a-paper}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Tools}\label{sec:tools}
It is certain that using the right tool for any task is half way to success. And writing is no exception. Our favorite tools for writing papers are the following:
\begin{itemize}
\item \LaTeX: a high-quality free typesetting system; it includes features designed for the production of technical and scientific documentation. It is the \textit{de facto} standard for the communication and publication of scientific documents for hard sciences (\cref{table:latex});
\item \texttt{BibDesk}: an open-source reference management software package for macOS, used to manage bibliographies and references when writing essays and articles. It is primarily a BibTeX front-end for use with \LaTeX\ (see \cref{sec:bibdesk});
\item \texttt{JabRef}: an open-source and cross-platform reference management software package. Its use is similar to \texttt{BibDesk}. It is primarily a BibTeX front-end for use with \LaTeX. One great feature that we like: it fetches bibliography entries automatically when given a DOI;
\item \texttt{Skim}: an open-source PDF (Portable Document Format) reader for macOS. Alternatives are \texttt{Sumatra PDF} for Windows and \texttt{evince} for Linux;
\item \texttt{Adobe Illustrator}: an industry-standard vector graphics software to create high quality drawings;
\item \texttt{Inkscape}: a free and open-source vector graphics editor available for Linux, macOS, and Windows;
\item \texttt{Matplotlib}: a \texttt{Python} 2D plotting library which produces publication quality figures in a variety of hardcopy formats. It can be used in Python scripts;
\item \texttt{Dropbox}: on-going papers are stored in \texttt{Dropbox} so that we can access them from multiple devices;
\item \texttt{Git}: a distributed version-control system for tracking changes in source code during software development;
\item \texttt{GitHub} or \texttt{Gitlab}: online platforms that offer hosting for software development version control using \texttt{Git}. They offer both public and private (preferred for research papers) repositories. \texttt{Git} makes access papers from multiple devices and parallel collaboration on writing easy.
\end{itemize}
The flowchart for the generation of a paper is as follows. \LaTeX~ is used to typeset the paper. The references used in the paper are stored in a \texttt{.bib} file that is automatically generated and managed by \texttt{BibDesk} or \texttt{JabRef}. Sketches used in the paper are drawn using \texttt{Adobe Illustrator} or \texttt{Inkscape} and graphs are created using \texttt{Matplotlib}. Sketches and graphs are saved as PDF files and thus are of high quality (\cref{sec:figs}). Also, sketches and graphs could be generated such a way that the font used for embedded text is the same as that of the document.
To keep track of the changes in the code, figures, and even research data, \texttt{Git} is used. For collaborative writings, the git repository is hosted in either \texttt{Github} or \texttt{Gitlab}. They offer access to free private repositories that are very useful. The choice of using \texttt{Git} is because every co-author of the paper can work on the same paper simultaneously. (This paper was written that way.) Furthermore,
the co-authors can still use their own favorite \LaTeX\ editor\footnote{which is most often also their own coding editor.} (\eg the first author used \texttt{Sublime Text} while the last author used \texttt{Emacs}). We find this organization to be better than \texttt{Overleaf} at \url{https://www.overleaf.com}, which forces all authors to use a web-based \LaTeX\ editor.
\begin{table*}[h!]
\caption{Summary statistics of the use of \LaTeX\ in science disciplines (\% of submitted papers) taken from \url{https://www.the-scientist.com/uncategorized/dont-format-manuscripts-44040}.}
\centering
\setlength\fboxsep{0pt}
\vskip-\topsep%
\smallskip%
\renewcommand\arraystretch{1.4}
\colorbox{darkgray}{%
\begin{tabularx}{0.5\textwidth}{ll}
\toprule
Disciplines & \LaTeX\ rate \\
\midrule
Mathematics & 96.9\% \\
Statistic and Probability & 89.1\% \\
Physics & 74.0\%\\
Computer Sciences & 45.8\%\\
Engineering & 1.0\%\\
\bottomrule
\end{tabularx}%
}
\label{table:latex}
\end{table*}
% \begin{rmk}
% Note that \texttt{Bibdesk} is only available for mac OS. One can use \texttt{Zotero} or \texttt{Mendeley} for Windows and Linux computers. Alternatives to the quite pricey \texttt{Adobe Illustrator} are \texttt{GIMP} or \texttt{Inkscape}.
% \end{rmk}
\begin{rmk}\label{rm:a}
Without going into the debate of which is the best editor, we use \texttt{Sublime Text}. This is
because it can be used for both writing \LaTeX\ documents and coding. Furthermore, it can render equations in real time, see \cref{fig:sublime-text}, which is quite handy. And the two way sync between \texttt{Skim} and \texttt{Sublime Text} is super convenient. However, \texttt{Sublime Text} is proprietary. If you prefer open-sourced software, look into \texttt{Vim}, \texttt{VS Code}, and \texttt{Emacs}. Coupled with the \texttt{AucTex} package, \texttt{Emacs} can recognize \LaTeX\ code and compile it easily. We prefer using a general purpose text editor rather than a \LaTeX\ editor so that we just use one editor for both \LaTeX\ typesetting and coding.
\begin{figure}[h!]
\centering
\includegraphics[width=0.65\textwidth]{sublime-text}
\caption{\texttt{Sublime Text} can render equations in real time.}
\label{fig:sublime-text}
\end{figure}
\end{rmk}
\begin{rmk}\label{rm:a}
There are many alternatives to \texttt{matplotlib} such as \texttt{gnuplot} and \texttt{Matlab}. We used \texttt{Matlab} and recently switched to \texttt{Python}. There are many reasons that influenced this, two of which are noteworthy. First, it is fun and beneficial to the brain to learn something new. Second, \texttt{Python} is now everywhere: it is used as a scripting language for many finite element packages (e.g. \texttt{Abaqus}) and scientific visualization programs (\texttt{Paraview} and \texttt{Ovito} for example).
\end{rmk}
The tools described in this section help you to write papers effectively, only when you have an idea how a paper should look like, and how to write different components of a paper. The next section is devoted to just that.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Writing tips}\label{sec:writing-tips}
This section presents writing tips. We start with some general guidelines in \cref{sec:guidelines}. Then we discuss the paper structure in \cref{structure}; all major sections of a paper are treated: title, abstract, introduction, results, conclusions, appendices, and references. Next, we discuss equations in
\cref{sec:equation} and figures in \cref{sec:citing-figs}. How to construct sentences and paragraphs is outlined in \cref{sec:sentences,sec:paragraph}, respectively.
Some common mistakes and a few tips to make your paper less verbose or wordy are given next in
\cref{sec:mistakes}. Finally, \cref{sec:writing-process} -- the most significant contribution of the paper -- outlines an iterative writing process in which writing is intertwined with other research activities. Recently, we realized that this technique has been, not surprisingly, adopted by other researchers, \eg \cite{Jones}.
%--------------------------------------
\subsection{General guidelines}\label{sec:guidelines}
The following general guidelines for a high quality scientific paper are nothing new but they are worth being repeated:
\begin{enumerate}
\item The purpose of a paper is to inform not to impress;
\item The writers should aim for clarity, readability, and reproducibility;
\item Contributions must be clearly stated;
\item Every unit of discourse (a sentence, a paragraph, a section, and the entire article), regarless of the size, conveys only a single idea or message \citep{gopen1990science,savage2019novelist}\footnote{Watch also the interesting talk of Judy Swan at \url{https://www.youtube.com/watch?v=1pzjxYCwb08}.};
\item Avoid jargon and abbreviations;% Writing a paper is not a race for complexity. You should make it as simple as possible for a neophyte reader to understand;
\item Figures should be of high quality (\eg at least the font is legible).
%\item Minimize chances for reviewers to raise issues.
\end{enumerate}
The main contributions of your paper must be clearly stated after a brief review of the literature: in which way your work differs from the existing literature. Be precise, as this is where the reviewers will try to find problems with your work. Their goal is to identify whether your work is novel or not. If it is not immediately clear from the Abstract and Introduction you risk being unconvincing.
Avoid jargon which are the specialized vocabulary of any profession, trade, science. Writing a paper is not a race for complexity. You should make it as simple as possible for a neophyte reader to understand.
Our advice is try to avoid jargon in the abstract and introduction as much as possible so that your paper is more accessible to a wide range of audience. In case that a jargon is needed, provide a definition for it the first time it appears in the paper, and also include clarifications for any poorly formed jargon.
Consider the following sentence appearing in an abstract:
\begin{quote}
\textit{There are different formulations to model the tension/compression asymmetry of fracture.}
\end{quote}
The jargon ``tension/compression asymmetry'' might not be clear to some audiences. A better version of the above is:
\begin{quote}
\textit{There are different formulations to model the tension/compression asymmetry of
fracture -- fracture does not occur in domains under compression.}
\end{quote}
Reproducibility is a big issue in scientific research nowadays. Reproducibility requires that findings can be verified independently. We, however, confine ourselves here just to the situation where a published simulation result is genuinely correct but impossible to reproduce by people other than the authors. The world would be a better place if all authors are more thoughtful when reporting their results: all information needed to make that particular simulation work should be provided. Particularly, nontrivial parameters.
You can save time for both you -- the authors -- and the reviewers and the readers by not making them guess. For example, if you do not do large deformation simulations, make it clear and justify that choice. If you have used a particular value for one numerical parameter, explain your choice. The bottom line is: \textit{Explain everything}; if something is obvious to you does not mean that it is obvious to your reader. If the reviewers have to guess your choices, they will comment on that. This increases the chances for your paper to be rejected, or needing corrections. When that happened you have lost your valuable time.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{How to structure your paper}\label{structure}
Typically a paper in the field of computational engineering and sciences consists of the following parts:
\begin{itemize}
\item Title
\item Abstract
\item Introduction
\item Methods
\item Results
\item Conclusions
\item Acknowledgments
\item Appendices
\item References
\end{itemize}
In this section we discuss some suggestions on how to write these parts. We start with titles in \cref{sec:title}, which is followed by \cref{sec:abstract} on the abstract part. We, then, present a way to organize long sections by having a global paragraph before going into its subsections (\cref{sec:global-para}). Next, we discuss how to write a compelling introduction section (\cref{sec:introduction-part}). After that, we discuss the results section (\cref{sec:result}) and the conclusion section (\cref{sec:conclusion-part}). Appendices and footnotes are discussed in \cref{sec:appendix-footnotes} and references in \cref{sec:references}.
An excellent article on how to structure a scientific paper can be found at \url{https://www.nature.com/scitable/topicpage/scientific-papers-13815490/}. There are certainly overlaps between it and our discussion.
\subsubsection{Title}\label{sec:title}
Why should you pay more attention to the title of your paper? This is because
\begin{itemize}
\item the title is the part of a paper that is read the most;
\item it is usually read first; and thus a good title gives a good first impression;
\item papers with short titles got more citations \citep{paiva2012articles};
\item using a question mark in a paper’s title reduces the citations;
\item using a colon tended to improve the citations.
\end{itemize}
What a good title look like then? It should
\begin{itemize}
\item indicate accurately the subject and the scope of the study;
\item reveal the significance of the paper;
\item contain no abbreviations;
\item exclude phrases such as "study of," "analysis of" or similar constructions.
\end{itemize}
For example, the following title
\begin{quote}
\textit{An efficient and robust staggered algorithm applied to the quasi-static description
of brittle fracture by a phase-field approach}
\end{quote}
can be modified to make it better
\begin{quote}
\textit{An efficient and robust staggered solver for a phase-field model of quasi-static
brittle fracture}
\end{quote}
\subsubsection{Abstract}\label{sec:abstract}
The abstract of a paper is the most important section of your paper. This is so because it is the second section that is read by journal editors (they read your cover letter first). Furthermore, once your paper has been published, its abstract is the first section that is clearly examined by readers. And in many cases, it is the only section of the manuscript that will be ever read. Sadly, many authors write the abstract in a great rush, almost as an afterthought (probably too eager to let the paper go?).
The abstract should be a concise standalone summary of your paper. It must include the background, gaps, methodology and results. In other words, it answers these questions: Why did you do the study? What did you do? What did you find? What did you conclude? \cref{fig:abstract} presents an example of a good abstract. We label it a good abstract because it answers the above questions.
\begin{figure}[h!]
\centering
\includegraphics[width=0.86\textwidth]{abstract}
\caption{Example of a good abstract, taken from \cite{de2021modelling}.}
\label{fig:abstract}
\end{figure}
\subsubsection{Global paragraph for long sections}\label{sec:global-para}
For paragraphs that are quite complex it is a good idea to write a global paragraph (or mini-introduction) between the heading of a section and the heading of its first subsection. The idea is to prepare your readers for the structure ahead at all levels; not doing so might make your reader lost. See \cref{fig:section} for an example.
\begin{figure}[!h]
\centering
\includegraphics[width=0.9\textwidth]{section}
\caption{A complex section should have a global paragraph between the heading of a section and the heading of its first subsection.}
\label{fig:section}
\end{figure}
Papers on the field of computational engineering and sciences always have a section, typically named `Numerical Examples' where some tests are presented to demonstrate the performance of the model/theory presented. While these examples are most often presented in order of increasing complexity, we can do a better job in presenting them. For example, a global paragraph stating why these examples were chosen, which open source (if it is the case) code was used, etc. We first saw this technique probably in \cite{huang2003modeling}. Furthermore, a table with all parameters used for all simulations would be helpful, see \eg \cref{table:params}, as it is harder to get them if they are embedded in the text.
\subsubsection{Introduction section}\label{sec:introduction-part}
Everyone would agree that the introductory section of a paper should answer the following questions, in order:
\begin{enumerate}
\item What is the problem that the paper is solving;
\item Why that problem is considered (the importance of the problem);
\item What are the current approaches to solving this problem and what is wrong about them;
\item What are the contributions of the paper;
\end{enumerate}
And it should also plan the readers for reading the subsequent sections.
It is not an easy task to write an introductory section that (i) answers all the above questions, (ii) covers all relevant works, (iii) is easy to follow and (iv) is short. What we commonly see in the literature is introductory sections of about two to three pages, full of just plain text with lots of jargons. There are two problems with this type of writing. First, only the authors and a dozens of experts can understand what is going on. Second, the paper loses many readers. We have realized that using some formula, figures, tables in the introduction section significantly improves the readability.
See \cref{algo-static-FEM} for an example, taken from \cite{Mandal:EFM2019}.
%---------------------------------------------------------------------------------------
\begin{MyBox}[label={algo-static-FEM}]
{Equations and tables can improve the introduction section.}
According to second-order PFMs for quasi-static fracture of solids under the infinitesimal strain regime, the displacement field $\bfu$ and damage field $d$ are minimizers of the following total energy functional of the solid
\begin{equation*}
\mathscr{E} (\bfu, d)
= \int_{\varOmega_{0}} \left[\omega(d)\psi_{0}^+(\bfepsilon (\bfu)) + \psi_{0}^-(\bfepsilon (\bfu)) \right]\td V
+ \int_{\varOmega_{0}} \frac{G_\text{f}}{c_\alpha} \left[ \frac{1}{b} \alpha(d)
+ b \left( \nabla d \cdot \nabla d \right) \right] \td V
- \mathscr{P} (\bfu)
\label{eq:3}
\end{equation*}
where the first integral is the stored strain energy, the second one denotes the fracture energy \`a la Griffith. The positive and negative parts of the strain energy density are denoted by $\psi_{0}^+(\bfepsilon (\bfu))$ and $\psi_{0}^-(\bfepsilon (\bfu))$, respectively.\\
\begin{tabularx}{\textwidth}{lllllll}
\toprule
model & $\alpha(d)$ & $\omega(d)$ & fracture type & length-scale & sup. & Parameters\\
\midrule
\texttt{AT2} & $d^2$ & $(1 - d)^{2}$ & brittle & $b=(27/256) l_{\text{ch}}$ & $\infty$ & $E_0,\nu_0,G_\text{f},b$ \\
\texttt{AT1} & $d$ & $(1 - d)^{2}$ & brittle & $b=(3/8) l_{\text{ch}}$ & $4b$ & $E_0,\nu_0,G_\text{f},b$\\
\texttt{PF-CZM} & $2d-d^2$ & $\dfrac{(1 - d)^p}{(1 - d)^p + Q(d)}$ & brittle/cohesive & numerical param. & $\pi b$ & $E_0,\nu_0,G_\text{f},f_t$\\
\bottomrule
\end{tabularx}%
\end{MyBox}
One way to visually demonstrate the contributions of your paper is to use a table in which a comparison with previous models is given. We borrowed this idea from the computer graphics community, see e.g. \cite{Stomakhin:TG2013a}. We have adopted this idea in \cite{Vaucorbeil:AAM2019} where we have provided a table (\cref{tab:summary}) where we compared different variants of the material point method (MPM).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\vspace*{3mm}
\begin{table*}[h!]
\centering
\caption{Overall characteristics of common MPM variants. The smileys and frownies are typeset using the package \texttt{wasysym}. }
\setlength\fboxsep{0pt}
\vskip-\topsep%
\smallskip%
%\renewcommand\arraystretch{1.3}
\colorbox{darkgray}{%
\begin{tabularx}{0.99\textwidth}{lllllll}
\toprule
MPM variant & Efficiency & Quad. error & Cell crossing & Num. fracture & Grid type & Contacts \\
\midrule
MPM & \smiley{} \smiley{} \smiley{} & \frownie{} \frownie{} \frownie{} & yes & yes & Cartesian/unstructured & \smiley{} \\
GIMP & \smiley{} \smiley{} & \frownie{} \frownie{} & no & yes & Cartesian & \smiley{} \\
CPDI & \smiley{} \smiley{} & \frownie{} & no & no & Cartesian& \smiley{} \\
TLMPM & \smiley{} \smiley{} \smiley{} \smiley{} & \frownie{} & no & no & Cartesian/unstructured& \frownie{} \\
iMPM & \smiley{} & \frownie{} & no & n/a & n/a & n/a \\
\bottomrule
\end{tabularx}%
}
\label{tab:summary}
\end{table*}
Another way to intrigue readers is to summarize all the impressive simulations that the model presented in your paper can do in a figure (see \cref{fig:all-results}). In this way, you increase the chance that your paper gets read to the end.
\begin{figure}[!h]
\centering
\includegraphics[width=0.5\textwidth]{mpm-all-results}
\caption{A figure with all good results that the model in your paper can deliver can help to intrigue readers so that they will read your paper to the end. Taken from \cite{Vaucorbeil:AAM2019}.}
\label{fig:all-results}
\end{figure}
\subsubsection{Results section}\label{sec:result}
In many fields a paper contains one section discussing the results and one section ``Discussions'' to elaborate on the results. However, in the field of computational mechanics, most often these two are combined into one section named ``Numerical examples'' or the likes.
As we have discussed in \cref{sec:global-para} for a long and complex section we need to have a global paragraph planning the reader. For the Results section, this global paragraph should explain: (1) what examples are considered and for what purposes (without doing so some readers won't care about your examples or experiments), (2) which codes are used and (3) what not considered and reason of doing so. If all these details are given it is easier for the reviewers and the researchers transitioning to a new field to know what is going on. \cref{fig:examples} presents such a global paragraph.
\begin{figure}[h!]
\centering
\includegraphics[width=0.87\textwidth]{examples}
\caption{A global paragraph planning the reader for the Results section.}
\label{fig:examples}
\end{figure}
For each example, before presenting the results, we should also help the reader by stating what is the question that we want to find answer with it, and what qualitative and quantitative measures are used for that purpose. For example, for example 1, we can write:
\begin{quote}
\textit{
The aim of this example is to verify if the proposed method provides mesh convergent results. To this end, we consider four finite element meshes of increasing number of elements, and for each mesh we monitor the load-displacement measured at point $P$ (see Fig.1). The method is said to be mesh convergence if the load-displacement plots converge for the used meshes.
}
\end{quote}
\subsubsection{Conclusion section}\label{sec:conclusion-part}
There are two misunderstandings about the Conclusion section. First, the Conclusion section is usually made long under the false belief that a longer Conclusion will seem more impressive. Second, it is most often just a replication of the Abstract and/or part of the Introduction in a present perfect tense. If the reader has to read your Conclusion to know what your paper is all about, then your Abstract and Introduction were not well written.
Some papers with well written sections even do not have a conclusion section. We are not a fan of that and believe having a conclusion is a good thing. Following the Nature paper introduced at the beginning of this section, a well written conclusion section should include the following items:
\begin{itemize}
\item A brief summary (one or two sentences) of what the paper is about;
\item A summary of the key findings of the paper;
\item A list of potential improvements.
\end{itemize}
The key findings can be presented using bullet points. And as far as bullet points are concerned, we have to mention parallel structure. Parallel structure means that coordinate parts of a sentence, such as items in a series or list, have the same grammatical form.
For example, in a draft version, one student of ours wrote (in the introduction section): We present the following concrete contributions:
\begin{itemize}
\item A unified fourth order phase field fracture framework for brittle and quasi-brittle solids which can be considered as an extension of the unified PFM of Wu (2017);
\item A semi-analytical (analytical-numerical) approach for PF-CZM;
\item A almost length scale insensitive fourth order PFM;
\item The first fourth order PFM for cohesive fracture;
\item The PF-CZM is applied to study the phenomena of crack kinking in anisotropic brittle fracture
\end{itemize}
We do not need to be a native English to recognize that the above list is wrong. Just by reading it out loud we can see that the first three bullet points are ok, but there is something wrong with the fourth and fifth bullets.
Using parallel structure, the above list must be written as follows: We present the following concrete contributions:
\begin{itemize}
\item A unified fourth order phase field fracture framework for brittle and quasi-brittle fracture;
\item A semi-analytical approach for the fourth order PF-CZM;
\item A comparison of the fourth order PF-CZM against the second order PF-CZM;
\item A study of the phenomena of crack kinking and saw-tooth cracking in strongly anisotropic brittle fracture.
\end{itemize}
Parallel structures can be used in sentences and in paragraphs.
\subsubsection{Appendix and footnotes}\label{sec:appendix-footnotes}
It is appropriate to include appendices when
the incorporation of material in the body of the paper would make it poorly structured or it would be too long and detailed and to ensure inclusion of supporting material that would otherwise clutter or break up the narrative flow of the paper.
As discussed later in \cref{sec:equation}, it is better to move some equations to an appendix.
There are opposite ideas about footnotes. Some authors use them scarcely and some use them extensively. The argument of the former is that footnotes \textit{break the flow of thoughts and send your eyes darting back and forth while your hands are turning pages or clicking on links} according to Pulitzer prizewinner novelist Cormac McCarthy \citep{savage2019novelist}. The argument of the latter is probably to reduce the paper's length. But, we find one wrong thing about footnotes: too lengthy footnotes. Some papers contain footnotes that are half a page long and with a smaller font than the main text. These are not readable.
We use footnotes sparingly and they are most often short. If you find a long footnote, consider using a remark as we have done in \cref{rm:a}.
\subsubsection{References}\label{sec:references}
You should pick one reference style and stick to it so that the references are consistent. Regarding how relevant work should be cited, below are some suggestions:
\begin{itemize}
\item Cite originals not derivatives;
\item Avoid citing a list of two many papers \eg `See [1-20] for some relevant work'. This helps neither the readers to find anything, nor the authors of [1-20] to get credit;
\item Cite all references in a single citation with a author-year reference format chronologically. For instance, `To help ease the writing process, books and articles giving advice on how to write scientific papers have been written \citep{day1998write,ashby2000write,plaxco2010art}.'
\end{itemize}
\subsection{Notations and equations}\label{sec:equation}
Avoid overly complex notations, see \cref{tab:complex-notation} for some examples. Try to introduce a nomenclature in the paper, to ease things for the reviewers and readers. Sometimes, a table such as \cref{tab:notations} does a good job to introduce main notations.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table*}[h!]
\centering
\caption{Avoid overly complex notations.}
\setlength\fboxsep{0pt}
\vskip-\topsep%
\smallskip%
%\renewcommand\arraystretch{1.3}
\colorbox{darkgray}{%
\begin{tabularx}{0.3\textwidth}{ll}
\toprule
Don't & Do \\
\midrule
$\varkappa$ & $\kappa$ \\
$\hbar$ & $\bar{h}$ \\
$\underline{\underline{A}}$ & $\boldsymbol{A}$ or $A_{ij}$\\
\bottomrule
\end{tabularx}%
}
\label{tab:complex-notation}
\end{table*}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table*}[h!]
\caption{Major notations can be put in a table.}
\centering
\setlength\fboxsep{0pt}
\vskip-\topsep%
\smallskip%
%\renewcommand\arraystretch{1.3}
\colorbox{darkgray}{%
\begin{tabularx}{0.6\textwidth}{llX}
\toprule
Variable & Type & Meaning\\
\midrule
$\mathbf{x}_p$ & Vector & Particle position (time-dependent)\\
$\mathbf{X}_p$ & Vector & Particle initial position\\
$m_p$ & Scalar & Particle mass\\
$V_p$ & Scalar & Particle volume\\
$\rho_p$ & Scalar & Particle density\\
$T_p$ & Scalar & Particle temperature\\
$\mathbf{P}_p$ & Tensor/Matrix & Particle 1$^\text{st}$ Piola-Kirchoff stress\\
\bottomrule
\end{tabularx}%
}
\label{tab:notations}
\end{table*}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Ideally, the impact of a scientific work should be determined by its scientific merit, rather than by presentational style. Unfortunately, \cite{Fawcett11735,Higginson_2016} showed that scientifically strong papers may have reduced impact if not presented in an accessible manner.
The density of equations in an article on ecology and evolutionary biology has a significant negative impact on citation rates, with papers receiving 28\% fewer citations overall for each additional equation per page in the main text \citep{Fawcett11735}. For papers in physics, the number is 6\% fewer citations for each additional equation per page \citep{Higginson_2016}.
The lesson to learn from the above relation between the density of equations in a paper and its impact is to write less equations in the body of the paper. This can be achieved by removing unnecessary equations. If needed, some equations can be put in appendices.
A paper in the field of computational sciences certainly contains some mathematical equations and/or expressions. To demonstrate how equations are written, we use the following one (taken from one of our papers)\footnote{Many \LaTeX\ editors have support to find \LaTeX\ symbols for those mathematical symbols. But, \texttt{Sublime Text} does not. You can then check out \texttt{detexify} at \url{http://detexify.kirelabs.org/classify.html}. This web app lets you draw a symbol, and shows you the closest \LaTeX\ symbols.}
\begin{equation}
\mathscr{E} (\bfu, d)
= \int_{\varOmega_{0}} \left[\omega(d)\psi_{0}^+(\bfepsilon (\bfu)) + \psi_{0}^-(\bfepsilon (\bfu)) \right]\td V
+ \int_{\varOmega_{0}} \frac{G_\text{f}}{c_\alpha} \left[ \frac{1}{b} \alpha(d)
+ b \left( \nabla d \cdot \nabla d \right) \right] \td V
- \mathscr{P} (\bfu)
\label{eq:energy-functional}
\end{equation}
where the first term is the strain energy, the second term is the surface energy and the third term the external energy. Collectively, they define the energy of the mechanical system $\mathscr{E} (\bfu, d)$\footnote{Any mathematical symbols appearing in the text must be typeset using a math font. In \latex this is achieved by putting the symbols in two dollar signs. }.
Note that we have "voiced out" the above equation in "words" so that the reader will have one more way of understanding, and the equations will not look as blunt and intimidating, in particular when you have a lot of notation which does not appear in literature. Later on we refer to this equation using its number as: \textit{The energy functional in \cref{eq:energy-functional} is minimized to obtain ...}
We do not want to discuss about punctuation in equations as this problem is still a debate. Do whatever you feel comfortable with. But the editor can ask you to add punctuation in your equations!
\subsection{Figures}\label{sec:citing-figs}
Figures are an important element of reporting the findings of your research. The reader usually starts by reading the abstract, conclusion and figures. If the figures are self-contained and convincing, it is likely that the reviewers will accept the paper without asking a large number of questions. If they have to read the whole text to understand the worth of each figure, this will slow their progress and could make them impatient, hence decrease the chance of giving recommendation for your paper.
A high quality figure is worth a thousand words. By a high quality figure we meant the one that has a legible font size, a high resolution, is color-blindness aware, of which all the axes are clearly defined, those sorts of things. Later on we will discuss how to prepare such figures (\cref{sec:figs}). We emphasize the importance of high quality figures because we have seen so many figures which are, without better words, of very low quality.
Tables and figures, although important components of any research papers, are just that--components; you can publish a paper without them but you cannot publish tables or figures without a paper. Thus a figure (or table) exists to support the text. So the first rule is: make sure that every table and figure is mentioned in the text. Even though there are some \LaTeX\ packages (\eg \texttt{Refcheck}) that help to find out unused figures and tables, our practice is when we insert a figure in our document, we cite it immediately. And the second rule is: remove any figure if it does not support your discussion. The third rule is: writing good figure captions. Thus, pay attention to the figure captions. Ideally, the reader should be able to ascertain the entire story just by reading the figure captions \ie without going back and forth between the figure and the text sections. And the final rule is how figures/tables are referred to in the text.
One usually does not pay enough attention to how figures (and tables) should be referred to in the text. That is why one usually write the following sentences
\begin{quote}
\textit{Fig. 10 depicts the global responses. As can be seen, the global responses are
insensitive to the incorporated length scale.}
\end{quote}
The first sentence is unnecessary as it only directs the reader to the figure (Fig. 10), and thus it provides no information. We have found similar sentences in the literature (including our papers). A better version of the above sentence is:
\begin{quote}
\textit{The global responses are insensitive to the incorporated length scale (Fig. 10).}
\end{quote}
We say that this is better because it did not use the phrase ``As can be seen''. It is clear that the use of too many such phrases should (and can be) be avoided. Another way to get rid of ``as can be seen'' is
\begin{quote}
\textit{Fig. 10 depicts the global responses. There we observe that the global responses are
insensitive to the incorporated length scale.}
\end{quote}
Actually we already use this style when we cite published articles and books to support an argument. We can do the same thing with figures and tables. We refer to the very readble textbook on nonlinear dynamics \citep{strogatz_nonlinear_1994} to see how Strogatz--an excellent writer--refers to figures in the text. For a more accessible source, we can refer to our own paper \textit{On a new high order phase field model for brittle and cohesive fracture: numerical efficiency, length scale convergence and crack kinking} in Computational Materials Science. This is probably the first paper in which we paid attention to how figures/tables are cited in the text.
\subsection{Sentences}\label{sec:sentences}
For writing sentences, we recommend the advice of Cormac McCarthy \citep{savage2019novelist}
\begin{quote}
Keep sentences short, simply constructed and direct. Concise, clear sentences work well for scientific explanations. Minimize clauses, compound sentences and transition words -- such as ‘however’ or ‘thus’ -- so that the reader can focus on the main message.
\end{quote}
Don't worry too much about grammatically perfect sentences. It is more important to be understood \citep{savage2019novelist}.
\noindent\textbf{Passive vs active voice}. Sentences can be written using either an active voice or passive voice. The active voice focuses on the agent: "David measured the temperature." (Here, the agent--David--is the subject of the sentence). In contrast, the passive voice focuses on the object that is acted upon: "The temperature was measured by David".
To choose between active and passive voice, consider what you are discussing and place it in the subject position. Using the above example of measurement of temperature, it is obvious that the temperature is the focus. So, we should write: "The temperature was measured." David was omitted because no matter who measured the temperature we would expect its value to be the same.
A common belief is that the passive voice can be useful for making the writing sound more formal and objective.
Unfortunately, this demand for objectivity of the writing has led to an overuse of the passive voice in scientific writing. For example, we see sentences similar to the below one all the time:
\begin{quote}
\textit{In this section, a discussion of the influence of the temperature on the deformation of ... is presented.}
\end{quote}
This sentence is not only boring but also verbose. Look at the following equivalent sentence using an active voice:
\begin{quote}
\textit{This section discusses the influence of the temperature on the deformation of ...}
\end{quote}
This sentence is shorter and easier to understand. Therefore, a systematic preference for the passive voice is by no means optimal. Use both in your papers and note that using a personal tone can help to engage a reader.
\subsection{Paragraphs}\label{sec:paragraph}
Each paragraph conveys only a single idea or message. Do not be afraid of writing short paragraphs, even two-sentence ones.
Use simple sentences that are linked together so that your writing is coherent.
See \cref{version1} for a paragraph that was not well written: the second sentence is not related to the first one and ``this issue'' in the third sentence was not clear. A better version is shown in \cref{version2} where the writing is more coherent: sentences start with the familiar (old) information and end with unfamiliar (new) information. We prefer the new, important information at the end, because its job is to intrigue the reader.
\begin{MyBox}[width=0.48\textwidth,nobeforeafter,label={version1}]
{Version 1.}
{\tcbfontsize{0.8}
In the phase-field modeling of fracture in brittle and quasi-brittle solids, it is crucial to represent the \textbf{asymmetric tensile/compressive material behavior}. \textbf{Existing phase-field models generally adopt either an intuitive split of the free energy density without capturing the crack boundary conditions properly or an ad hoc hybrid formulation at the loss of variational consistency}. \textbf{To address this issue}, this work presents a variationally consistent phase-field anisotropic damage model.}
\end{MyBox}\hfill
\begin{MyBox}[width=0.48\textwidth,nobeforeafter,label={version2}]
{Version 2.}
{\tcbfontsize{0.8}
In the phase-field modeling of fracture in brittle and quasi-brittle solids, it is crucial to represent the \textbf{asymmetric tensile/compressive material behavior}. \textbf{To capture this asymmetric behavior}, previous phase-field models generally adopt either and intuitive split of the free energy density without capturing the crack boundary conditions properly ... This work presents a phase-field anisotropic model that is able to capture \textbf{the asymmetric behavior}, \textbf{variationally consistent} and satisfy \textbf{crack boundary conditions}.}
\end{MyBox}
Another example is, from S.P. Jones (yes, the same Jones who has written the interesting paper on how to write great papers \citep{Jones})
\begin{quote}
\textit{Security proofs} of cryptographic protocols are crucial for the security of everyday electronic communication. However, \textit{these proofs} tend to be complex and difficult to get right. To make it easier to manage \textit{such proofs}, Jones et al. have proposed a new design principle, called the \textit{game-playing technique}.
\textit{This technique} follows a code-based approach where the security properties are formulated in therms of probabilistic programs, called games.
\end{quote}
We refer to the old article of \cite{gopen1990science} for more examples of writing readable paragraphs.
Try to revise your writing to keep only the words/figures/tables that are necessary: The main message of \textit{The Elements of Style} is to omit unnecessary words \citep{strunk2007elements}. For example, using `because' is more advisable than the wordy `due to the fact that' (see \cref{tab:mistakes} for a list of unnecessary words/phrases).
%
%--------------------------------------
\subsection{Some common mistakes}\label{sec:mistakes}
Some common mistakes are given in \cref{tab:mistakes}. You could have avoided these mistakes by carefully studying the writing of your favorite author (whoever she/he is). Anyway, we collect them here in one table as a checklist (the first author refer to this quite often to avoid these mistakes).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table*}[h!]
\caption{Some common mistakes. A good way to improve your writing is by reading your writing, including all of the writing out loud. Your ears can often pick out sentence fragments and grammatical errors better than your eyes. If you find yourself saying a series of fragmented sentences or feeling something unnatural, you should do some rewriting.}
\centering
\setlength\fboxsep{0pt}
\vskip-\topsep%
\smallskip%
%\renewcommand\arraystretch{1.3}
\colorbox{darkgray}{%
\begin{tabularx}{\textwidth}{ll}
\toprule
Don't/Avoid & Do/Use \\
\midrule
\textbf{The} Table/Figure 2 & Table/Figure 2 \\
\textbf{The} Equation (2.2) & Equation (2.2) \\
\textbf{The} Young's modulus & Young's modulus, or the Young modulus\\
Start a section with a table/figure/equation & Start a section with text\\
This topic has interested researchers for a \textbf{long} time & ... for more than 20 years\\
A \textbf{bad} result & A poor/negative result\\
This section \textbf{serves} to explain & This section explains\\