forked from djtomlinson/PhysiBoSS
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathUser_Guide.tex
7637 lines (6142 loc) · 275 KB
/
User_Guide.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[12pt]{article}
\newcommand{\Version}{1.7.1}
\newcommand{\ReleaseDate}{June 2, 2020}
\usepackage[letterpaper,margin=0.5in,bottom=0.75in]{geometry}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{dsfont}
\usepackage{bbm}
\usepackage{stmaryrd}
\usepackage{graphicx}
\usepackage{pbox}
\usepackage{hyperref}
\usepackage{changepage}
\usepackage[dvipsnames,usenames]{color}
\setcounter{tocdepth}{4}
\setcounter{secnumdepth}{4}
\usepackage{caption}
\captionsetup{justification=raggedright,singlelinecheck=false}
\usepackage{tikz}
\usetikzlibrary{arrows,automata,arrows.meta}
\usepackage{mdframed}
\mdfdefinestyle{mystyle}{
backgroundcolor=lightgray!10,
innertopmargin=5mm,
innerbottommargin=5mm,
innerleftmargin=5mm,
innerrightmargin=5mm
}
\usepackage{bold-extra}
\hypersetup{
pdftitle={PhysiCell User Guide \Version},
pdfauthor={Paul Macklin and the PhysiCell Project},
pdfsubject={PhysiCell},
pdfproducer={http://MathCancer.org},
pdfkeywords={PhysiCell,agent-based model,simulation},
colorlinks=true,
linkcolor=blue,
citecolor=red,
filecolor=magenta,
urlcolor=blue
}
\usepackage[square,comma,numbers,sort&compress]{natbib}
\usepackage[nottoc]{tocbibind}
\newcommand{\braces}[1]{\left\{#1\right\}}
\newcommand{\abs}[1]{\left|#1\right|}
\renewcommand{\vec}[1]{\mathbf{#1}}
\newcommand{\mean}[1]{\langle #1 \rangle}
\newcommand{\norm}[1]{\left|\left|{#1}\right|\right|}
\newcommand{\beq}{\begin{equation}}
\newcommand{\eeq}{\end{equation}}
\newcommand{\beqa}{\begin{eqnarray}}
\newcommand{\eeqa}{\end{eqnarray}}
\newcommand{\beqaN}{\begin{eqnarray*}}
\newcommand{\eeqaN}{\end{eqnarray*}}
\newcommand{\micron}{\mu\textrm{m}}
\newcommand{\specialcell}[2][c]{%
\begin{tabular}[#1]{@{}c@{}}#2\end{tabular}}
\newcommand{\boldrho}{\rho\hspace{-5.1pt}\rho}
% \newcommand{\grvec}[1]{#1\hspace{-6pt}#1\hspace{-6pt}#1\hspace{1pt}}
\newcommand{\grvec}[1]{\boldsymbol{#1}}
\newcommand{\one}{\mathds{1}}
\newcommand{\hp}{\circ}%{\odot}%{\circ}
\newcommand{\hd}{\hspace{-1.6mm}\fatslash}%{\oslash}'
\setlength{\parskip}{1em}
\setlength{\parindent}{0in}
\newcommand{\code}[1]{\verb|#1|}
\renewcommand{\v}{\verb}
\renewcommand{\t}[1]{\left[\mathrm{#1}\right]}
\renewcommand{\tt}[1]{{\small \left[\texttt{#1}\right] }}
\newcommand{\smallcode}[1]{\textbf{\texttt{#1}}}
%\newcommand{\smallcode}[1]{\textbf{\v|#1|}}
\newcommand{\red}[1]{\textcolor{red}{#1}}
\newcommand{\blue}[1]{\textcolor{blue}{#1}}
\newcommand{\magenta}[1]{\textcolor{magenta}{#1}}
\newcommand{\FIX}{}%{\textbf{\red{[FIX ME]}}}
\newcommand{\DONE}{}%{\textbf{\blue{[DONE]}}}
\newcommand{\FINISH}{}%{\magenta{[FINISH ME]}}
\newcommand{\TOClink}{\begin{center}\hrule\vskip-5pt\phantom{.}\hfill[Return to \hyperlink{TOC}{Table of Contents}.]\hfill\phantom{.}\vskip3pt\hrule\end{center}}
\begin{document}
\author{PhysiCell Project (Lead: Paul Macklin)}
\title{PhysiCell User Guide (Version \Version)}
\date{Revision: \ReleaseDate}%\today}
\maketitle
\setlength{\parskip}{0in}
\hypertarget{TOC}{}
\tableofcontents
\setlength{\parskip}{8pt}
\section{Introduction and citing PhysiCell \DONE}
This user guide will teach you how to download and use PhysiCell \cite{ref:PhysiCell},
as well as document the key classes and functions. Wherever possible, it will demonstrate
with specific examples. Please note that this guide will be periodically updated. Users
should check \href{http://PhysiCell.MathCancer.org}{PhysiCell.MathCancer.org} for the latest version.
The PhysiCell method paper was published in PLoS Computational Biology \cite{ref:PhysiCell}. \\
\\
If you use PhysiCell, please cite it as: \\
\\
\phantom{ }\hspace{.075\textwidth}\parbox[top]{0.85\textwidth}{%
We implemented and solved our model using PhysiCell (Version \Version) [1]. \\
[1] A. Ghaffarizadeh, R. Heiland, S.H. Friedman, S.M. Mumenthaler, and P. Macklin. PhysiCell: an Open Source Physics-Based Cell Simulator for 3-D Multicellular Systems, PLoS Comput. Biol. 14(2): e1005991, 2018. DOI: \href{https://dx.doi.org/10.1371/journal.pcbi.1005991}{10.1371/journal.pcbi.1005991}. } \\
\\
Because PhysiCell makes extensive use of BioFVM, we suggest you also cite it:
\phantom{ }\hspace{.075\textwidth}\parbox[top]{0.85\textwidth}{%
We implemented and solved the model using PhysiCell (Version \Version) [1], with BioFVM [2] to solve the transport equations. \\
[1] A Ghaffarizadeh, R Heiland, SH Friedman, SM Mumenthaler, and P Macklin. PhysiCell: an Open Source Physics-Based Cell Simulator for Multicellular Systems, PLoS Comput. Biol. 14(2): e1005991, 2018. DOI: \href{https://dx.doi.org/10.1371/journal.pcbi.1005991}{10.1371/journal.pcbi.1005991} \\
[2] A Ghaffarizadeh, SH Friedman, and P Macklin. BioFVM: an efficient parallelized diffusive transport solver for 3-D biological simulations, Bioinformatics 32(8): 1256-8, 2016. DOI: \href{https://dx.doi.org/10.1093/bioinformatics/btv730}{10.1093/bioinformatics/btv730}
}
\textbf{Please remember:} if you use an additional addon, please make sure to cite it, too! This is critical for scientific rigor (to correctly document your method), reproducibility, and good academic behavior.
We have started testing methods to auto-generate suggested citations for addons; see the auto-generated CITATION.txt when you run your model. This will be further developed in future versions of PhysiCell.
\TOClink
\section{Getting started: The Quickstart and your First Simulation}
\label{sec:getting_started}
As of Version 1.2.2, every download of PhysiCell includes a \v|Quickstart.pdf| guide in the root
directory. If you follow the instructions in that guide (along with instructions to
set up your compiler and environment; see Section \ref{sec:preparing_environment}), you should
be able to run and visualize your first PhysiCell simulation (heterogeneous tumor growth)
in well under an hour.
You should also watch the \href{https://twitter.com/search?f=tweets&vertical=default&q=PhysiCell&src=typd}{\#PhysiCell hashtag}
on Twitter for updates on PhysiCell and new tricks, tips, and tutorials.
Tutorials and other blog posts can be found at
\href{http://mathcancer.org/blog/physicell-tutorials/}{http://MathCancer.org/blog/physicell-tutorials/}.
See Section \ref{sec:blog_and_help} for resources for help, including support tickets and the PhysiCell blog.
\TOClink
\section{Further resources for help}
\label{sec:blog_and_help}
The PhysiCell project posts tips and tutorials at its blog:
\begin{center}
\href{http://www.mathcancer.org/blog/physicell-tutorials/}{http://www.mathcancer.org/blog/physicell-tutorials/}
\end{center}
Users are encouraged to frequently visit the blog for these tips. This user manual may
be updated more frequently than PhysiCell. Please check the PhysiCell project website for
updates:
\begin{center}
\href{http://PhysiCell.MathCancer.org}{http://PhysiCell.MathCancer.org}
\end{center}
Lastly, users can support help tickets at SourceForge:
\begin{center}
\href{https://sourceforge.net/p/physicell/tickets/}{https://sourceforge.net/p/physicell/tickets/}
\end{center}
\TOClink
\section{Preparing your development environment \DONE}
\label{sec:preparing_environment}
PhysiCell was designed to be cross-platform compatible, without need for a package manager system or any other
complex installation. In principle, any \v|C++11| compliant compiler with OpenMP support should work. In
practice, we use \v|g++| as our ``gold standard.'' You'll also want to ensure that your build environment supports
makefiles. Command-line zip/unzip is also helpful, but not required.
Please note that OSX (and its associated developer tools)
ships with ``\v|g++|'' instead of \v|g++|: it uses LLVM/Clang and an alias to \emph{pretend} to be \v|g++|.
Unfortunately, the version of LLVM/Clang that Apple ships does not fully support OpenMP, and so compiling can
fail on those platforms without further setup. For OSX, we recommend following our
Homebrew-based tutorial to install real \v|g++|.
Full tutorials on installing a 64-bit \v|g++|/OpenMP environment (on Windows via mingw-w64 and on OSX using Homebrew)
can be found at:
\href{http://www.mathcancer.org/blog/physicell-tutorials/}{http://www.MathCancer.org/blog/physicell-tutorials/}
Most linux users should already have a 64-bit \v|g++| environment installed by default.
\TOClink
\subsection{Special notes for OSX users}
\label{sec:osx_setup_note}
As of Version 1.2.2, OSX users no longer need to modify the \v|CC| definition in the makefiles--this
represents a significant simplification for those users. However, OSX users (including those who
have already installed \v|g++| by Homebrew of MacPorts) need to perform a one-time setup
of an environment variable. Open your terminal, and run the following commands:
\begin{verbatim}
export PHYSICELL_CPP=your_compiler_name
echo export PHYSICELL_CPP=your_compiler_name >> ~/.bash_profile
\end{verbatim}
\v|your_compiler_name| will be something like \v|g++-7| for Homebrew installations,
and something like \v|g++-mp-7| for MacPorts installations.
See the tutorials at
\href{http://www.mathcancer.org/blog/physicell-tutorials/}{http://www.MathCancer.org/blog/physicell-tutorials/}
for more details. Also, if you have compiler crashes, see the FAQ (frequently asked questions) at:
\href{http://www.mathcancer.org/blog/common-problems-and-solutions/}{http://www.mathcancer.org/blog/common-problems-and-solutions/}
\TOClink
\subsection{Virtual Machine option \DONE}
Starting with the 1.2.x releases, we began distributing PhysiCell as zipped source (preferred) %,
% \href{https://www.docker.com/}{Docker} containers,
and virtual appliances for use in \href{http://virtualbox.org}{VirtualBox} and other virtual machine software,
allowing us to distribute a full PhysiCell
development environment (including 64-bit \v|g++|, support for makefiles, zip/unzip,
ImageMagick, mencoder, eog, a text editor, and the most up-to-date
version of PhysiCell). This should make it simpler to start learning and using PhysiCell, even in cases
where developers are not free to install or modify their own build environments,
or have difficulty installing and configuring \v|g++|.
Please visit the
\href{http:/PhysiCell.MathCancer.org/blog/physicell-tutorials}{PhysiCell blog}
for information on running VirtualDub and using the virtual appliance.
(Section \ref{sec:blog_and_help}).
Note that we do not update the Virtual Box distribution; you should download the latest PhysiCell version from inside your virtual machine.
\TOClink
%\subsection{Docker option \DONE}
%Starting with the 1.2.x releases, we began distributing PhysiCell as zipped source (preferred) and
%\href{https://www.docker.com/}{Docker} containers of PhysiCell, allowing us to distribute a full PhysiCell
%development environment (including 64-bit \v|g++|, support for makefiles, zip/unzip, a text editor, and the most up-to-date
%version of PhysiCell). This should make it simpler to start learning and using PhysiCell, even in cases
%where developers are not free to install or modify their own build environments,
%or have difficulty installing and configuring \v|g++|.
%
%Please visit the
%\href{http:/PhysiCell.MathCancer.org/blog/physicell-tutorials}{PhysiCell blog}
%to check for blog posts on running Docker.
%(Section \ref{sec:blog_and_help}).
%\TOClink
\subsection{Suggested tutorials and resources\DONE}
Working in PhysiCell requires some knowledge of \v|C++|, Makefiles, and command-line routines in Unix-like systems.
If you are not familiar with these skillsets, we recommend the following resources:
\subsubsection{Linux and Makefile tutorials}
\begin{enumerate}
\item
\textbf{A tutorial on learning the Linux shell:} \href{http://linuxcommand.org/lc3_learning_the_shell.php}{http://linuxcommand.org/lc3\_learning\_the\_shell.php} \\
In particular, I recommend:
\begin{enumerate}
\item \href{http://linuxcommand.org/lc3_lts0010.php}{What is ``The Shell''?}
\item \href{http://linuxcommand.org/lc3_lts0020.php}{Navigation}
\item \href{http://linuxcommand.org/lc3_lts0030.php}{Looking Around}
\item \href{http://linuxcommand.org/lc3_lts0050.php}{Manipulating Files}
\end{enumerate}
\item \textbf{UNIX Tutorial for Beginners: } \href{http://www.ee.surrey.ac.uk/Teaching/Unix/}{http://www.ee.surrey.ac.uk/Teaching/Unix/} \\
In particular, I suggest the following:
\begin{enumerate}
\item \href{http://www.ee.surrey.ac.uk/Teaching/Unix/unix1.html}{Tutorial 1} (navigation, creating directories, etc.)
\item \href{http://www.ee.surrey.ac.uk/Teaching/Unix/unix2.html}{Tutorial 2} (moving, copying files, etc.)
\item \href{http://www.ee.surrey.ac.uk/Teaching/Unix/unix4.html}{Tutorial 4} (wildcards, filename conventions, etc.)
\item \href{http://www.ee.surrey.ac.uk/Teaching/Unix/unix7.html}{Tutorial 7} (compiling and running software, etc.)
\item \href{http://www.ee.surrey.ac.uk/Teaching/Unix/unix8.html}{Tutorial 8} (UNIX and environment variables, etc.) (\textbf{Note:}
May not work in Windows/MinGW.)
\end{enumerate}
\item \textbf{The GNU Bash Reference Manual:} \href{http://www.gnu.org/software/bash/manual/bash.html}{http://www.gnu.org/software/bash/manual/bash.html}
\item
\textbf{A good makefile tutorial:} \href{http://www.cprogramming.com/tutorial/makefiles.html}{http://www.cprogramming.com/tutorial/makefiles.html}
\item
\textbf{Another good makefile tutorial:} \href{http://mrbook.org/blog/tutorials/make/}{http://mrbook.org/blog/tutorials/make/}
\item
\textbf{One more makefile tutorial:} \href{http://makefiletutorial.com/}{http://makefiletutorial.com/}
\item
\textbf{The GNU Make Reference:} \href{https://www.gnu.org/software/make/manual/make.html}{https://www.gnu.org/software/make/manual/make.html}
\end{enumerate}
\TOClink
\subsubsection{C++ references}
The following websites are good references for \v|C++|:
\begin{enumerate}
\item
\textbf{CPlusPlus.com:}
\href{http://www.cplusplus.com/}{http://www.cplusplus.com/}\\
Excellent, detailed documentation on \v|C++|, as well as tutorials.
\item
\textbf{C++ Reference:}
\href{http://en.cppreference.com/w/}{http://en.cppreference.com/w/}\\
Another good reference guide to \v|C++|.
\item
\textbf{LearnCpp.com:}
\href{http://www.learncpp.com/}{http://www.learncpp.com/} \\
A series of tutorials on \v|C++|.
\item
\textbf{StackOverflow (C++ tag):}
\href{https://stackoverflow.com/questions/tagged/c%2b%2b}{https://stackoverflow.com/questions/tagged/c\%2b\%2b}\\
A sometimes overwhelming resource for problem solving in \v|C++|.
\item
\textbf{C++ section on CodeGuru:}
\href{http://www.codeguru.com/cpp/cpp/}{http://www.codeguru.com/cpp/cpp/}
\end{enumerate}
\TOClink
\subsubsection{Matlab tutorials}
If you use Matlab for visualization and/or postprocessing, we recommend:
\begin{enumerate}
\item
\textbf{MATLAB tutorials at Mathworks:} \hfill\break
\href{https://www.mathworks.com/academia/student_center/tutorials/mltutorial_launchpad.html}{https://www.mathworks.com/academia/student\_center/tutorials/mltutorial\_launchpad.html}
\item
\textbf{Introduction to MATLAB for Engineering Students:} \href{https://www.mccormick.northwestern.edu/documents/students/undergraduate/introduction-to-matlab.pdf
}{http://bit.ly/2cQBXDc}
\item
\textbf{A Beginner's Guide to MATLAB: }
\href{http://homen.vsb.cz/~lud0016/NM/matlab_guide.pdf}{http://homen.vsb.cz/\~{}lud0016/NM/matlab\_guide.pdf
} \\
(By Christos Xenophontos at Loyola College).
\item
\textbf{MATLAB Academy:}
\href{https://matlabacademy.mathworks.com/?s_eid=ppc_23223967642}{https://matlabacademy.mathworks.com/?s\_eid=ppc\_23223967642}
\item
\textbf{MATLAB Tutorial:}
\href{https://www.tutorialspoint.com/matlab/}{https://www.tutorialspoint.com/matlab/}
\item
\textbf{Octave:} If you do not have access to MATLAB or prefer an open source
alternative, have a look at this cross-platform package: \\
\href{https://www.gnu.org/software/octave/}{https://www.gnu.org/software/octave/}
\end{enumerate}
\TOClink
\subsubsection{VirtualBox and related information (virtual appliances)}
If you use the virtual appliance, we suggest the following tutorials and resources:
\begin{enumerate}
\item
\textbf{VirtualBox:} \href{http://virtualbox.org}{http://virtualbox.org}\\
This is an excellent cross-platform (Windows, Linux, OSX, etc.) virtual machine software
that can import the virtual appliance version of PhysiCell. %
%
\item
\textbf{Alpine Linux:} \href{https://alpinelinux.org/}{https://alpinelinux.org/}\\
Alpine Linux is a lean and secure version of linux we installed in the PhysiCell
virtual appliance. %
%
\item
\textbf{Alpine Linux Wiki:}
\href{https://wiki.alpinelinux.org/}{https://wiki.alpinelinux.org}\\
A helpful site for using Alpine Linux. %
%
\item
\textbf{VirtualBox shared folders in Alpine:} \hfill \break
\href{https://wiki.alpinelinux.org/wiki/VirtualBox_shared_folders}{https://wiki.alpinelinux.org/wiki/VirtualBox\_shared\_folders
}%
%
\item
\textbf{Alpine Linux users forum:}
\href{https://forum.alpinelinux.org/
}{https://forum.alpinelinux.org/
}%
%
\item
\textbf{XFCE4 project:}
\href{https://xfce.org/}{https://xfce.org/}\\
We use the XFCE4 desktop environment in our virtual appliance, so this may be helpful.
\end{enumerate}
\TOClink
% \subsubsection{Docker resources}
% If you use Docker, we suggest the following tutorials:
%
% \begin{enumerate}
% \item
% \textbf{Docker user introduction:} \href{https://docs.docker.com/get-started/}{https://docs.docker.com/get-started/}
%
% \item
% \textbf{Docker for beginners:} \href{https://prakhar.me/docker-curriculum/}{https://prakhar.me/docker-curriculum/}
%
% \item
% \textbf{Docker tutorial:} \href{https://www.tutorialspoint.com/docker/}{https://www.tutorialspoint.com/docker/}
% \end{enumerate}
% \TOClink
\subsubsection{Recommended additional tools}
Lastly, we find the following tools and resources very useful for postprocessing
and visualization:
\begin{enumerate}
\item
\textbf{ImageMagick} is a cross-platform image manipulation suite, which can (among other things)
resize and crop images, change formats, and insert text labels. In PhysiCell, ImageMagick is especially
useful for converting SVG files to PNG, JPG, or other raster-based formats for further animation.
\begin{itemize}
\item\textbf{URL:}
\href{http://imagemagick.org}{http://imagemagick.org}
\item\textbf{Typical use:} \v|magick mogrify -format jpg snapshot*.svg| \\
\hspace{1in}(Converts all files of the form snapshot*.svg to the png format.)
\item\textbf{Typical use:} \v|magick snapshot*.jpg animation.gif| \\
\hspace{1in}(Combines all snapshot*.jpg files into a (huge!) animated gif file.)
\end{itemize}
\item
\textbf{Mencoder} is a cross-platform, open source mpeg encoder, useful for creating compressed
movies. In PhysiCell, we use mencoder to convert series of simulation snapshots to movies.
\begin{itemize}
\item \textbf{URL (Linux):} Use your package manager to install mplayer (which includes mencoder).
\item \textbf{URL (OSX):} Use Homebrew or MacPorts to install mplayer (which includes mencoder).
\item \textbf{URL (Windows):} \href{http://mplayerwin.sourceforge.net/}{http://mplayerwin.sourceforge.net/}
\item \textbf{Typical use:} \\
% \footnotesize\v|mencoder "mf://*.jpg" -ovc lavc -mpegopts format=mpeg4:vbitrate=8000 -nosound fps=24 -o out.mp4|\normalsize \\
\normalsize\v|mencoder "mf://snapshot*.jpg" -ovc lavc -lavcopts| \\
\normalsize\v| vcodec=mpeg4:vbitrate=10000:mbd=2:trell -mf fps=24:type=jpg -nosound -o out.avi|\normalsize \\
\hspace{1in}(Converts all the snapshot*.jpg files into an mpeg4-encoded movie named out.avi, with a 8kbps variable bit rate and 24 frames per second.)
\end{itemize}
\end{enumerate}
\TOClink
\section{Overall codebase structure \DONE}
PhysiCell was created by extending the \v|Basic_Agent| class in BioFVM \cite{ref:BioFVM} to include a fuller cell phenotype
and force-based cell motion. In the overall software philosophy, we structure PhysiCell in several critical
subdirectories:
\begin{enumerate}
\item
\smallcode{BioFVM} This includes a working copy of the BioFVM multi-substrate diffusion code \cite{ref:BioFVM}. Users should be able
to fully replace these files with any later version of BioFVM. Note that BioFVM distributions also include
pugixml (an efficient cross-platform XML parser) \cite{ref:pugixml}.
\item
\smallcode{beta} This directory is used for beta functionality used by our team during
testing and development. Use at your own risk!
\item
\smallcode{config} This directory is used for XML configuration files with. Any custom configuration files should be placed in this directory.
\item
\smallcode{core} The core library files for PhysiCell are kept in this directory. Users should not modify functions in
the core library.
\item
\smallcode{custom\_modules} This directory is the right place to put custom user code. Moreover, users should
list their custom code files in \v|custom_modules/PhysiCell_custom.h|.
\item
\smallcode{modules} This is where we place non-core (but helpful) standard code modules for distribution with PhysiCell.
Currently, we include pathology, MultiCellDS \cite{ref:MultiCellDS}, and SVG (scalable vector graphic) functions.
Future releases may include basic modules for extracellular matrix.
\end{enumerate}
The following subdirectories are also included:
\begin{enumerate}
\item
\smallcode{archives} If you use the \v|make zip| or \v|make archive| rules, the compressed archives will be placed here.
\item
\smallcode{documentation} This directory includes user guides (like this one!).
\item
\smallcode{matlab} This includes basic Matlab files for handling PhysiCell outputs. (This and other postprocessing
will be a major PhysiCell focus over the next few years.)
\item
\smallcode{examples} The examples from the PhysiCell method paper will be placed here. They may not
necessarily be updated for compatibiltiy with every PhysiCell release. (They are currently compatible up to version
1.1.1.)
\item
\smallcode{licenses} License files for BioFVM \cite{ref:BioFVM}, pugixml \cite{ref:pugixml}, PhysiCell,
and any other (BSD-compatible) dependencies are kept here.
\item
\smallcode{output} Some examples will put their outputs here.
\item
\smallcode{povray} This includes some basic utilities for visualization by povray (an open source raytracing package) \cite{ref:povray}.
\item
\smallcode{sample\_projects} This directory includes sample projects, including 2D and 3D template projects
and at least the four sample projects in \cite{ref:PhysiCell}. A good start to a new
project is to use the \v|make template2D| or \v|make template3D| makefile rules,
which will populate the \v|main.cpp|, \v|Makefile|, and \v|./custom_modules| with appropriate
codes to get started. See Section \ref{sec:templates} for more information on the
template projects, and Section \ref{sec:sample_projects} for the full list of sample
projects and instructions to build them.
\end{enumerate}
\subsection{Time step sizes in PhysiCell}
\label{sec:time_steps}
PhysiCell uses three time step sizes:
\begin{enumerate}
\item
\v|diffusion_dt| is the step size used in the diffusion solver, including the secretion/export and uptake processes.
The default value is 0.01 min.
\item
\v|mechanics_dt| is the step size for the cell mechanics solver, including cell motility.
Each cell's custom function is also evaluated on this time scale. The default value is 0.1 min.
\item
\v|phenotype_dt| is the step size for phenotype processes (e.g., cycle progression, volume changes).
The default value is 6 min.
\end{enumerate}
As of PhysiCell 1.6.1, these values can be set in the XML configuration file. See Section
\ref{sec:XML_PhysiCell_structure}.
\TOClink
\section{Using project templates \DONE}
\label{sec:templates}
As of Version 1.1.0, PhysiCell includes templates for 2-D and 3-D projects. These template projects set up all
the critical BioFVM (microenvironment) and PhysiCell data structures and give examples on seeding a few
cells. When beginning a new project with PhysiCell, we strongly recommend starting with these templates.
To start a new 2-D project (based on the template), go to the command line in the root PhysiCell directory,
and run:
\v|make template2D|
This will populate a starting project from the files in \v|./sample_projects/template2D/|. In particular,
it will overwrite the \v|Makefile|, copy \v|template_projects/template2D.cpp| to \v|main.cpp| in the root directory,
and copy the contents of \v|./sample_projects/template2D/custom_modules/| to \v|./custom_modules|.
Note that the \v|Makefile| has been modified to include the custom modules:
\begin{verbatim}
# put your custom objects here (they should be in the custom_modules directory)
PhysiCell_custom_module_OBJECTS := custom.o
##### and later in the Makefile ...
# user-defined PhysiCell modules
custom.o: ./custom_modules/custom.cpp
$(COMPILE_COMMAND) -c ./custom_modules/custom.cpp
\end{verbatim}
In general, your project should modify main.cpp, but primarily add custom codes to
\v|./custom_modules|, just as this example. (For example, you might define your own
angiogenesis functions in \break
\v|./custom_modules/angiogenesis.h|, implement the functions
in \v|./custom_modules/angiogenesis.cpp|, and then modify the \v|Makefile| to include
it:
\begin{verbatim}
# put your custom objects here (they should be in the custom_modules directory)
PhysiCell_custom_module_OBJECTS := custom.o angiogenesis.o
##### and later in the Makefile ...
# user-defined PhysiCell modules
custom.o: ./custom_modules/custom.cpp
$(COMPILE_COMMAND) -c ./custom_modules/custom.cpp
angiogenesis.o: ./custom_modules/angiogenesis.cpp
$(COMPILE_COMMAND) -c ./custom_modules/angiogenesis.cpp
\end{verbatim}
This is the recommended structure for a project.
Once you're ready, build the project by typing
\v|make|
By default, the executable will be called \v|project2D| (\v|project2D.exe| on windows). To
change the name of the executable, modify the \v|PROJECT_NAME| variable in the \v|Makefile|.
To start a new 3-D project based on a template, type \v|make template3D| and continue as before.
Now, run the code:
\v|./project2D|
(in Windows, omit the ``\v|./|''.) This will generate (among other things) a series of \href{https://en.wikipedia.org/wiki/Scalable_Vector_Graphics}{SVG} images
that visualize the simulation once per hour.
More examples will be introduced on the PhysiCell blog. See
Section \ref{sec:blog_and_help}.
% are introduced in Section \ref{sec:examples}, including a tutorial that modifies the 2-D template project .
\TOClink
\section{Using the Sample Projects}
\label{sec:sample_projects}
PhysiCell includes several sample projects to illustrate capabilities and
suggest modeling possibilities. In general, building and running these projects
consists of the following steps:
\begin{enumerate}
\item
\textbf{Populate a project:} Use the following Makefile rule (from a terminal / command
project in your PhysiCell root directory):
\v|make [project_name]|
where \v|[project_name]| is one of the sample projects listed below. For example, to
populate the ``cancer biorobots'' sample project:
\v|make cancer-biorobots-sample|
\item
\textbf{Build the project:} Just run make:
\v|make|
\item
\textbf{Run the project:} Run the executable created by the compiler. If the name
of the program is \v|[PROGRAM_NAME]|, run
\v|./[PROGRAM_NAME]|
(Windows users should omit the \v|./|.)
One simple way to determine the name of the executable is to use grep on the Makefile:
\v|grep PROGRAM_NAME Makefile|
For example, to run the cancer biorobots example, the executable name is
\v|cancer_biorobots|, so you run:
\v|./cancer_biorobots|
The project will create a series of SVG images files, as well as MultiCellDS save files
(a combination of matlab and XML files). See \ref{sec:matlab_data} and
the PhysiCell blog.
\item
\textbf{(Optional) Clear out the project / return to a clean slate:} If you want
to build and run a different sample project, or clear out the sample materials
to create your own, you need to ``de-populate'' the sample project:
\v|make reset|
\end{enumerate}
Here are the sample projects included as of Version 1.2.2:
\begin{enumerate}
\item
\smallcode{biorobots-sample} is a 2-D example of 3 cell types: cargo cells, worker cells (which seek out cargo cells and
haul them to a destination), and director cells (which attract worker cells).
\item
\smallcode{cancer-biorobots-sample} extends the biorobots example to (1) simulate a 2-D tumor that develops a necrotic
core, (2) so that cargo cells are hauled towards hypoxic tumor regions, and (3) so that released cargo cells secrete
a chemotherapeutic compounds.
\item
\smallcode{heterogeneity-sample} simulates a 2-D tumor with heterogeneous ``genetics'' that drive differential proliferation.
\item
\smallcode{cancer-immune-sample} extends the heterogeneity example to 3D, and introduces a new immune
cell type (modeling T cells) that migrate towards tumor cells, temporarily adhere, test for immunogenicity,
and initiate apoptosis.
\item
\smallcode{virus-macrophage-sample} simulates a basic virus that diffuses, is uptaken by cells, replicates,
and then is released in cell lysis. Macrophages eat and degrade infected cells. This is a test of internalized
substrate tracking first released in PhysiCell 1.5.0.
\item
\smallcode{beta-testing} is a small project that can be used for beta testing new features. Don't count on
it remaining unchanged from release to release.
\item
\smallcode{template2D} is the template for a 2-D project. See Section \ref{sec:templates}.
\item
\smallcode{template3D} is the template for a 3-D project. See Section \ref{sec:templates}.
\end{enumerate}
\TOClink
\subsection{Extra makefile rules}
\label{sec:makefiles}
To clear out the data generated in a simulation:
\v|make data-cleanup|
To clear out the compiler-generated objects (which would allow you to recompile the entire project):
\v|make clean|
To reset to a clean slate (e.g., to clear out a sample project and populate another):
\v|make reset|
To get a list of all sample projects:
\v|make list-projects|
\TOClink
\section{The BioFVM microenvironment}
\label{sec:BioFVM}
PhysiCell is built upon BioFVM \cite{ref:BioFVM}, and so it uses the (bio)chemical microenvironment from BioFVM,
including diffusion, decay, cell-based secretions/export/uptake, and bulk supply/uptake functions. All
PhysiCell projects already include bioFVM once you have included PhysiCell:
\v|#include "./core/PhysiCell.h"|
We also suggest using the BioFVM and PhysiCell namespaces:
\begin{verbatim}
using namespace BioFVM;
using namespace PhysiCell;
\end{verbatim}
\subsection{Notes on the microenvironment}
\label{sec:about_BioFVM_microenvironment}
BioFVM divides the simulation domain into a collection of non-intersecting \textbf{voxels}: volumetric
pixels. Each voxel has a unique integer \textbf{index}: this is its unique address,
for quickly accessing its information. As particularly notable information, each
voxel stores its own position (center) and volume.
BioFVM adds one or more diffusible substrates to this microenvironment. Each substrate has a
diffusion coefficient and decay rate. At present, these are homogeneous throughout the microenvironment,
although improvements are planned for BioFVM to have spatially variable diffusion coefficients. In
BioFVM, each substrate diffuses and decays, and can be secreted or uptaken by individual
cells (see Section \ref{sec:Secretion}) at their individual positions.
As of PhysiCell 1.5.0, each cell can track the total amount of each substrate secreted and uptaken, and
pass half of it contents to its two daughter cells at division. Users can optionally set PhysiCell
to release the cell's internalized substrates at the end of death or lysis.
You can also set bulk uptake and secretion
functions, which are applied in each voxel. These are not used in the current template and sample
PhysiCell projects. See \cite{ref:BioFVM} for more information.
For each voxel, we store a vector of chemical substrates (densities), and a vector of gradients (one
gradient vector for each substrate). Moreover, users can use ``Dirichlet nodes'' to overwrite the
substrate values at any voxel within the simulation domain. This is useful for modeling biotransport
in irregular domains, setting substrate values along blood vessels, or applying classical Dirichlet conditions
along the outer edges of the simulation domain. Note that without specifying Dirichlet conditions,
BioFVM applies Neumann (no flux) conditions at the outer simulation boundaries.
\TOClink
\subsubsection{Biotransport equations}
\label{sec:biotransport_equations}
Based upon BioFVM \cite{ref:BioFVM}, PhysiCell solves the following system of partial differential equations (PDEs):
\beq
\frac{ \partial \grvec{\rho}}{\partial t}
= \vec{D} \circ \nabla^2 \grvec{\rho} - \grvec{\lambda} \circ \grvec{\rho} + \sum_i \delta \left( \vec{x} - \vec{x}_i \right)
\Bigl[ V_i \vec{S}_i \circ \left( \grvec{\rho}^*_i - \grvec{\rho} \right) - V_i \vec{U}_i \circ \grvec{\rho} + \vec{E}_i \Bigr],
\eeq
where
\begin{center}
\begin{tabular}{c|ll}
\textbf{Symbol} & Meaning & Dimensions\\
\hline \hline
$\boldrho $ & vector of substrate densities (or concentrations) & substance/volume \\
$\vec{D}$ & vector of diffusion coefficients & length$^2$/time \\
$\grvec{\lambda}$ & vector of decay rates & 1/time \\
$V_i$ & volume of cell $i$ & volume \\
$\vec{x}_i$ & cell $i$'s position (center) & length \\
$\vec{S}_i$ & vector of cell $i$'s secretion rates & 1/time \\
$\grvec{\rho}^*_i$ & vector of cell $i$'s secretion saturations & substance/volume\\
$\vec{U}_i$ & vector of cell $i$'s uptake rates & 1/time \\
$\vec{E}_i$ & vector of cell $i$'s net export rates & substance/time
\end{tabular}
\end{center}
\TOClink
\subsection{Setting up and using the microenvironment}
\label{sec:set_up_BioFVM}
\subsubsection{Specifying the microenvironment via XML (\sc{Preferred Method})}
\label{sec:BioFVM_setup_XML}
As of PhysiCell version 1.6.0, the chemical microenvironment can be completely
set up via the XML configuration file. (See also Section \ref{sec:XML_PhysiCell_structure} to
learn about the XML structure.) This is now the preferred method of setting up the chemical microenvironment,
as it can be done without recompiling a PhysiCell application and it provides easy
access to modify the physical parameters (diffusion and decay rates), boundary conditions,
and initial conditions.
See Section \ref{sec:XML_microenvironment_setup} for full documentation, including examples.
All these properties can also be manually edited within a PhysiCell
project via the C++ commands in Section \ref{sec:BioFVM_manual_setup_options}.
\TOClink
\subsubsection{Manual configuration via C++ function calls (\sc{Less Preferred Method})}
\label{sec:BioFVM_manual_setup_options}
Within your main program loop (\v|int main( int argc, char* argv[])|), you need to declare and
set up a Microenvironment. (Here, we also include some useful tips for setting space and time
units.) We make use of BioFVM 1.1.5 improvements that
include simplified setup functions.
%\subsubsection{Setting BioFVM options}
\paragraph{Setting BioFVM options}
\label{sec:BioFVM_options}
BioFVM 1.1.5 and later versions includes a data structure \hfill \newline
(\verb+default_microenvironment_options+, of type
\verb+Microenvironment_Options+) for setup options.
This data type is defined in \verb+BioFVM_microenvironment.h+ as:
\begin{verbatim}
class Microenvironment_Options
{
private:
public:
Microenvironment* pMicroenvironment;
std::string name;
std::string time_units;
std::string spatial_units;
double dx;
double dy;
double dz;
bool outer_Dirichlet_conditions;
std::vector<double> Dirichlet_condition_vector;
std::vector<bool> Dirichlet_activation_vector;
std::vector<double> initial_condition_vector;
bool simulate_2D;
std::vector<double> X_range;
std::vector<double> Y_range;
std::vector<double> Z_range;
Microenvironment_Options();
bool calculate_gradients;
bool use_oxygen_as_first_field;
bool track_internalized_substrates_in_each_agent;
};
\end{verbatim}
You can set these options either towards the top of your main program source
file (e.g., in \verb+main.cpp+) or in a standalone setup function. See
the sample projects for examples. Here is sample use, to set the tissue name to
``liver'' and set up to 3D with Dirichlet conditions of oxygen = 38 mmHg:
\begin{verbatim}
/* Microenvironment setup */
default_microenvironment_options.name = "liver";
default_microenvironment_options.time_units = "min";
default_microenvironment_options.spatial_units = "micron";
default_microenvironment_options.dx = 20;
default_microenvironment_options.dy = 20;
default_microenvironment_options.dz = 20;
// set a Dirichlet outer boundary condition
default_microenvironment_options.outer_Dirichlet_conditions = true;
std::vector<double> bc_vector( 1 , 38.0 ); // 5% o2
default_microenvironment_options.Dirichlet_condition_vector = bc_vector;
// set the initial oxygen concentration (uniform in the domain) at 42 mmHg:
default_microenvironment_options.initial_condition_vector = {42.0 };
// stick with a 3-D simulation
default_microenvironment_options.simulate_2D = false;
// set the domain size
default_microenvironment_options.X_range = {-500, 500};
default_microenvironment_options.Y_range = {-400, 400};
default_microenvironment_options.Z_range = {-100, 100};
// turn off gradient calculations
default_microenvironment_options.bool calculate_gradients = false;
// track internalized oxygen
default_microenvironment_options.track_internalized_substrates_in_each_agent = true;
\end{verbatim}
\TOClink
%\subsubsection{Adding new diffusing substrates to the tissue environment}
\paragraph{Adding new diffusing substrates to the tissue environment}
\label{sec:BioFVM_add_substrates}
By default, the BioFVM microenvironment has a single substrate (with index 0).
To add (append) a new substrate to the microenvironment, use one of these functions:
\begin{enumerate}
\item
\smallcode{void Microenvironment::add\_density( void )} Use this to add a new diffusing
substrate (density), without setting any of its properties.
\item
\smallcode{void Microenvironment::add\_density( std::string name , std::string units )} Use this
to add a new substrate called \v|name| with units \v|units|. (e.g., crayons with units Megacrayolas).
\item
\smallcode{void Microenvironment::add\_density( std::string name , std::string units, double diffusion\_constant, double decay\_rate )} acts similarly as above, but also sets the diffusion coefficient and decay rate. Generally,
these should be in the same units as the simulation: by default, $\micron^2/\textrm{min}$ for diffusion
and $1/\textrm{min}$ for decay.
\end{enumerate}
You can also change the name, units, and properties for an existing substrate:
\begin{enumerate}
\item
\smallcode{void Microenvironment::set\_density( int index , std::string name , std::string units )} This
function renames the substrate with index \v|index| to \v|name|, and sets its units to \v|units|.
\item
\smallcode{void Microenvironment::set\_density( int index , std::string name , std::string units ,
double diffusion\_constant , double decay\_rate )} works as above, but
also sets the diffusion coefficient and decay rate.
\end{enumerate}
For example,
\begin{verbatim}
// add a chemoattractant
microenvironment.add_density( "chemoattractant", "dimensionless" );
microenvironment.diffusion_coefficients[1] = 1e3;
microenvironment.decay_rates[1] = .1;
// add a therapeutic compound
microenvironment.add_density( "drug", "dimensionless" );
microenvironment.diffusion_coefficients[2] = 1e3;
microenvironment.decay_rates[2] = 0.15625;
// rename the first density to be glucose, and change parameters
microenvironment.set_density(0, "glucose", "dimensionless" );
microenvironment.diffusion_coefficients[0] = 1e3;
microenvironment.decay_rates[0] = 0.05625;
\end{verbatim}
You should always add or modify your substrates prior to initializing the microenvironment. See
Section \ref{sec:BioFVM_initialize}
\TOClink
% \subsubsection{Initializing the BioFVM tissue microenvironment}
\paragraph{Initializing the BioFVM tissue microenvironment}
\label{sec:BioFVM_initialize}
\begin{verbatim}
// initialize BioFVM with these options
initialize_microenvironment();
\end{verbatim}
BioFVM defaults to a 1 mm${}^3$ domain centered at
(0,0,0) with $\Delta x = \Delta y = \Delta z = 20 \:\micron$, simulating 3D with no Dirichlet conditions
and no gradient calculations, and minutes time units
and micron space units. If you call
\v|initialize_microenvironment()| without setting units (see Section \ref{sec:BioFVM_options}),
these defaults will be used.
The code also automatically chooses the correct
2D/3D diffusion solver, and sets the single diffusing
field to oxygen with diffusion coefficient
$10^5 \micron^2/\textrm{min}$ and decay coefficient
$0.1 \: 1/\textrm{min}$ (for a 1 mm diffusion length scale
in the absence of cells).
% \begin{verbatim}
% // time setup
% std::string time_units = "min";
% double t = 0.0; // current simulation time
%
% double t_output_interval = 60.0; // 60 minutes
% double t_max = 60*24*30; // 30 days
% double t_next_output_time = t;
% int output_index = 0; // used for creating unique output filenames
% \end{verbatim}
By the end of these commands, the default \v|Microenvironment| is
set to \v|microenvironment|. You can get this address at any time using
the BioFVM command:
\v|Microenvironment* get_default_microenvironment( void )|
% You might want to set Dirichlet (constant field) conditions along the outside boundary