diff --git a/doc/Projects/ProjectWriting/beamerthemered_plain.sty b/doc/Projects/ProjectWriting/beamerthemered_plain.sty new file mode 100644 index 000000000..a6b2d33bd --- /dev/null +++ b/doc/Projects/ProjectWriting/beamerthemered_plain.sty @@ -0,0 +1,12 @@ +\mode +\usecolortheme[rgb={0.8, 0.2, 0}]{structure} +\usefonttheme[onlysmall]{structurebold} + +\setbeamertemplate{navigation symbols}{} +%\setbeamertemplate{footline}[frame number] + +\usepackage{tikz} +\usetikzlibrary{arrows,shapes,backgrounds,decorations,mindmap} + +\mode + diff --git a/doc/Projects/ProjectWriting/beamerthemered_shadow.sty b/doc/Projects/ProjectWriting/beamerthemered_shadow.sty new file mode 100644 index 000000000..eff5ac479 --- /dev/null +++ b/doc/Projects/ProjectWriting/beamerthemered_shadow.sty @@ -0,0 +1,15 @@ +\mode + +\useoutertheme{smoothbars} +\useinnertheme[shadow=true]{rounded} +\usecolortheme{orchid} +\usecolortheme{whale} +\usecolortheme[rgb={0.7, 0.2, 0}]{structure} % (darker red) +\useoutertheme{shadow} +\usefonttheme[onlysmall]{structurebold} + +\setbeamercolor{title}{use=structure,fg=white,bg=structure.fg} +\setbeamerfont{block title}{size={}} + +\mode + diff --git a/doc/Projects/ProjectWriting/clean.sh b/doc/Projects/ProjectWriting/clean.sh new file mode 100644 index 000000000..2e5da2c72 --- /dev/null +++ b/doc/Projects/ProjectWriting/clean.sh @@ -0,0 +1,3 @@ +#!/bin/sh +doconce clean +rm -rf *.pdf *.tex ipynb*.tar.gz *.html ._*.html *~ reveal.js Trash README.txt diff --git a/doc/Projects/ProjectWriting/fig-projectwriting/procrast.jpg b/doc/Projects/ProjectWriting/fig-projectwriting/procrast.jpg new file mode 100644 index 000000000..359cd6de6 Binary files /dev/null and b/doc/Projects/ProjectWriting/fig-projectwriting/procrast.jpg differ diff --git a/doc/Projects/ProjectWriting/ipynb-projectwriting-src.tar.gz b/doc/Projects/ProjectWriting/ipynb-projectwriting-src.tar.gz new file mode 100644 index 000000000..d9fa190b5 Binary files /dev/null and b/doc/Projects/ProjectWriting/ipynb-projectwriting-src.tar.gz differ diff --git a/doc/Projects/ProjectWriting/make.sh b/doc/Projects/ProjectWriting/make.sh new file mode 100755 index 000000000..edfed7c87 --- /dev/null +++ b/doc/Projects/ProjectWriting/make.sh @@ -0,0 +1,118 @@ +#!/bin/sh +set -x + +function system { + "$@" + if [ $? -ne 0 ]; then + echo "make.sh: unsuccessful command $@" + echo "abort!" + exit 1 + fi +} + +if [ $# -eq 0 ]; then +echo 'bash make.sh slides1|slides2' +exit 1 +fi + +name=$1 +rm -f *.tar.gz + +opt="--encoding=utf-8" +# Note: Makefile examples contain constructions like ${PROG} which +# looks like Mako constructions, but they are not. Use --no_mako +# to turn off Mako processing. +opt="--no_mako" + +rm -f *.aux + + +html=${name}-reveal +system doconce format html $name --pygments_html_style=perldoc --keep_pygments_html_bg --html_links_in_new_window --html_output=$html $opt +system doconce slides_html $html reveal --html_slide_theme=beige + +# Plain HTML documents + +html=${name}-solarized +system doconce format html $name --pygments_html_style=perldoc --html_style=solarized3 --html_links_in_new_window --html_output=$html $opt +system doconce split_html $html.html --method=space10 + +html=${name} +system doconce format html $name --pygments_html_style=default --html_style=bloodish --html_links_in_new_window --html_output=$html $opt +system doconce split_html $html.html --method=space10 + +# Bootstrap style +html=${name}-bs +system doconce format html $name --html_style=bootstrap --pygments_html_style=default --html_admon=bootstrap_panel --html_output=$html $opt +system doconce split_html $html.html --method=split --pagination --nav_button=bottom + +# IPython notebook +system doconce format ipynb $name $opt + +# LaTeX Beamer slides +beamertheme=red_plain +system doconce format pdflatex $name --latex_title_layout=beamer --latex_table_format=footnotesize $opt +system doconce ptex2tex $name envir=minted +# Add special packages +doconce subst "% Add user's preamble" "\g<1>\n\\usepackage{simplewick}" $name.tex +system doconce slides_beamer $name --beamer_slide_theme=$beamertheme +system pdflatex -shell-escape ${name} +system pdflatex -shell-escape ${name} +cp $name.pdf ${name}-beamer.pdf +cp $name.tex ${name}-beamer.tex + +# Handouts +system doconce format pdflatex $name --latex_title_layout=beamer --latex_table_format=footnotesize $opt +system doconce ptex2tex $name envir=minted +# Add special packages +doconce subst "% Add user's preamble" "\g<1>\n\\usepackage{simplewick}" $name.tex +system doconce slides_beamer $name --beamer_slide_theme=red_shadow --handout +system pdflatex -shell-escape $name +pdflatex -shell-escape $name +pdflatex -shell-escape $name +pdfnup --nup 2x3 --frame true --delta "1cm 1cm" --scale 0.9 --outfile ${name}-beamer-handouts2x3.pdf ${name}.pdf +rm -f ${name}.pdf + +# Ordinary plain LaTeX document +rm -f *.aux # important after beamer +system doconce format pdflatex $name --minted_latex_style=trac --latex_admon=paragraph $opt +system doconce ptex2tex $name envir=minted +# Add special packages +doconce subst "% Add user's preamble" "\g<1>\n\\usepackage{simplewick}" $name.tex +doconce replace 'section{' 'section*{' $name.tex +pdflatex -shell-escape $name +pdflatex -shell-escape $name +mv -f $name.pdf ${name}-minted.pdf +cp $name.tex ${name}-plain-minted.tex + + + +# Publish +dest=../../pub +if [ ! -d $dest/$name ]; then +mkdir $dest/$name +mkdir $dest/$name/pdf +mkdir $dest/$name/html +mkdir $dest/$name/ipynb +fi +cp ${name}*.pdf $dest/$name/pdf +cp -r ${name}*.html ._${name}*.html reveal.js $dest/$name/html + +# Figures: cannot just copy link, need to physically copy the files +if [ -d fig-${name} ]; then +if [ ! -d $dest/$name/html/fig-$name ]; then +mkdir $dest/$name/html/fig-$name +fi +cp -r fig-${name}/* $dest/$name/html/fig-$name +fi + +cp ${name}.ipynb $dest/$name/ipynb +ipynb_tarfile=ipynb-${name}-src.tar.gz +if [ ! -f ${ipynb_tarfile} ]; then +cat > README.txt <\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "7ba5b916", + "metadata": { + "editable": true + }, + "source": [ + "# How to write a scientific project\n", + "**Morten Hjorth-Jensen**, Department of Physics, University of Oslo and Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University\n", + "\n", + "Date: **Sep 26, 2023**\n", + "\n", + "Copyright 1999-2023, Morten Hjorth-Jensen. Released under CC Attribution-NonCommercial 4.0 license" + ] + }, + { + "cell_type": "markdown", + "id": "41c36523", + "metadata": { + "editable": true + }, + "source": [ + "## The report: how to write a good scienfitic/technical report\n", + "**What should it contain? A typical structure.**\n", + "\n", + " * An abstract where you give the main summary of your work\n", + "\n", + " * An introduction where you explain the aims and rationale for the physics case and what you have done. At the end of the introduction you should give a brief summary of the structure of the report\n", + "\n", + " * Theoretical models and technicalities. This is the methods section\n", + "\n", + " * Code structure, tests and more\n", + "\n", + " * Results and discussion\n", + "\n", + " * Conclusions and perspectives\n", + "\n", + " * Appendix with extra material\n", + "\n", + " * Bibliography\n", + "\n", + "Keep always a good log of what you do." + ] + }, + { + "cell_type": "markdown", + "id": "c51fd68b", + "metadata": { + "editable": true + }, + "source": [ + "## The report, the abstract\n", + "The abstract gives the reader a quick overview of what has been done and the most important results. Here is a typical example\n", + "taken from a recent [scientific article](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.131.131401) \n", + "\n", + "**We construct the first four-dimensional multiple black hole solution of general relativity with a positive cosmological constant. The solution consists of two static black holes whose gravitational attraction is balanced by the cosmic expansion. These static binaries provide the first four-dimensional example of nonuniqueness in general relativity without matter.**\n", + "\n", + "If you have specific recommendations and/or results you may also highlight them in the abstract." + ] + }, + { + "cell_type": "markdown", + "id": "9d1dc01f", + "metadata": { + "editable": true + }, + "source": [ + "## The report, the introduction\n", + "**What should I focus on? Introduction.**\n", + "\n", + "You don't need to answer all questions in a chronological order. When you write the introduction you could focus on the following aspects\n", + " * Motivate the reader, the first part of the introduction gives always a motivation and tries to give the overarching ideas\n", + "\n", + " * What I have done\n", + "\n", + " * The structure of the report, how it is organized etc" + ] + }, + { + "cell_type": "markdown", + "id": "037721a1", + "metadata": { + "editable": true + }, + "source": [ + "## The report, discussion of methods\n", + "**What should I focus on? Methods sections.**\n", + "\n", + " * Describe the methods and algorithms\n", + "\n", + " * You need to explain how you implemented the methods and also say something about the structure of your algorithm and present some parts of your code\n", + "\n", + " * You should plug in some calculations to demonstrate your code, such as selected runs used to validate and verify your results. The latter is extremely important!! A reader needs to understand that your code reproduces selected benchmarks and reproduces previous results, either numerical and/or well-known closed form expressions." + ] + }, + { + "cell_type": "markdown", + "id": "9331e9e2", + "metadata": { + "editable": true + }, + "source": [ + "## The report, code part\n", + "\n", + "Try to make a GitHub/Gitlab etc repository with three folders\n", + "\n", + "1. One which contains the report\n", + "\n", + "2. One which contains some test runs and eventually additional results not presented in the report\n", + "\n", + "3. One which contains the code\n", + "\n", + "The code should be well documented and make sure it produces the results you are showing in the report. Here you can doucment soruce files and/or jupyter-notebooks.\n", + "\n", + "You may also add a README file which tells what is contained in the this repository." + ] + }, + { + "cell_type": "markdown", + "id": "f5b39fba", + "metadata": { + "editable": true + }, + "source": [ + "## The report, results part\n", + "**What should I focus on? Results.**\n", + "\n", + " * Present your results\n", + "\n", + " * Give a critical discussion of your work and place it in the correct context.\n", + "\n", + " * Relate your work to other calculations/studies\n", + "\n", + " * An eventual reader should be able to reproduce your calculations. All input variables should be properly explained.\n", + "\n", + " * Make sure that figures and tables should contain enough information in their captions, axis labels etc so that an eventual reader can gain a first impression of your work by studying figures and tables only." + ] + }, + { + "cell_type": "markdown", + "id": "d0d0928d", + "metadata": { + "editable": true + }, + "source": [ + "## The report, conclusions and perspectives\n", + "**What should I focus on? Conclusions.**\n", + "\n", + " * State your main findings and interpretations\n", + "\n", + " * Try as far as possible to present perspectives for future work\n", + "\n", + " * Try to discuss the pros and cons of the methods and possible improvements" + ] + }, + { + "cell_type": "markdown", + "id": "09a4c0ce", + "metadata": { + "editable": true + }, + "source": [ + "## The report, appendices\n", + "**What should I focus on? additional material.**\n", + "\n", + " * Additional calculations used to validate the codes\n", + "\n", + " * Selected calculations, these can be listed with few comments\n", + "\n", + " * Listing of the code if you feel this is necessary\n", + "\n", + "You can consider moving parts of the material from the methods section to the appendix or your GitHub/Gitlab repository. You can also place additional material on your webpage." + ] + }, + { + "cell_type": "markdown", + "id": "d6a360ce", + "metadata": { + "editable": true + }, + "source": [ + "## The report, references\n", + "**What should I focus on? References.**\n", + "\n", + " * Give always references to material you base your work on, either scientific articles/reports or books.\n", + "\n", + " * Refer to articles as: name(s) of author(s), journal, volume (boldfaced), page and year in parenthesis.\n", + "\n", + " * Refer to books as: name(s) of author(s), title of book, publisher, place and year, eventual page numbers" + ] + }, + { + "cell_type": "markdown", + "id": "4b7b0a94", + "metadata": { + "editable": true + }, + "source": [ + "## Where do I find scientific articles, books etc and examples of reports\n", + " * With a UiO IP number you can access freely all books and scientific journals available at our [University library](http://www.ub.uio.no/)\n", + "\n", + " * For scientific articles, go to for example the journal [Physical Review Letters of the American Physical Society](http://journals.aps.org/prl/issues/117/10)" + ] + }, + { + "cell_type": "markdown", + "id": "0fd05cf4", + "metadata": { + "editable": true + }, + "source": [ + "## Procrastination... the curse of all?\n", + "\n", + "\n", + "\n", + "

Figure 1:

\n", + "\n", + "\n", + "[Enjoy this video](https://www.youtube.com/watch?v=arj7oStGLkU)\n", + "\n", + "[And research shows that procrastinating enhances creativity!!](http://www.nytimes.com/2016/01/17/opinion/sunday/why-i-taught-myself-to-procrastinate.html?_r=0)" + ] + } + ], + "metadata": {}, + "nbformat": 4, + "nbformat_minor": 5 +}