From 625374175f081689ba6c3d9546ca3546305c7b9f Mon Sep 17 00:00:00 2001 From: Seb James Date: Sun, 19 Nov 2023 15:23:32 +0000 Subject: [PATCH] Starting to add contet --- docs/about.md | 33 +++++++++++++++++++++++ docs/core_classes/colourmap.md | 6 +++++ docs/core_classes/index.md | 20 ++++++++++++++ docs/core_classes/range.md | 6 +++++ docs/core_classes/scale.md | 6 +++++ docs/core_classes/vec.md | 48 +++++++++++++++++++++++++++++++++ docs/{ => core_classes}/vvec.md | 2 +- docs/index.md | 29 +------------------- docs/quick.md | 1 + docs/who.md | 6 +++++ docs/why.md | 19 +++++++++++++ 11 files changed, 147 insertions(+), 29 deletions(-) create mode 100644 docs/about.md create mode 100644 docs/core_classes/colourmap.md create mode 100644 docs/core_classes/index.md create mode 100644 docs/core_classes/range.md create mode 100644 docs/core_classes/scale.md create mode 100644 docs/core_classes/vec.md rename docs/{ => core_classes}/vvec.md (81%) create mode 100644 docs/who.md create mode 100644 docs/why.md diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 00000000..8b6f33b8 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,33 @@ +--- +title: What is morphologica? +layout: home +permalink: /about +order: 1 +--- + +morphologica is a library of header-only C++ code. + +If you're a C++ developer and you want to draw runtime graphs, surface plots or scatter plots that are **fast**, you are a member of the target demographic. + +morphologica provides **simulation support facilities** for simulations of dynamical systems, agent-based models or, in fact, any program that needs dynamic, runtime visualization. + +It helps with: + +* **OpenGL Visualizations of your program while it runs**. A modern OpenGL visualization + scheme called **[morph::Visual](https://github.com/ABRG-Models/morphologica/blob/main/morph/Visual.h)** + provides the ability to visualise 2D and 3D graphs + of surfaces, lines, bars, scatter plots and quiver plots with minimal + processing overhead. + +* **Configuration**: morphologica allows you to easily set up a simulation + parameter configuration system, using the JSON reading and writing + abilities of **[morph::Config](https://github.com/ABRG-Models/morphologica/blob/main/morph/Config.h)**. ([morph::Config Example](https://github.com/ABRG-Models/morphologica/blob/main/examples/jsonconfig.cpp)) + +* **Saving data from your simulation**. morphologica provides a set of + easy-to-use convenience wrappers (**[morph::HdfData](https://github.com/ABRG-Models/morphologica/blob/main/morph/HdfData.h)**) around the HDF5 C + API. By saving data in a standard format, it is easy to access + simulation data in python, MATLAB or Octave for analysis and graphing. ([HdfData Example](https://github.com/ABRG-Models/morphologica/blob/main/examples/hdfdata.cpp)) + +# What is this site for? + +It's to help you to learn how to use the classes in morphologica in your own numerical simulations and data analysis programs. \ No newline at end of file diff --git a/docs/core_classes/colourmap.md b/docs/core_classes/colourmap.md new file mode 100644 index 00000000..623e4480 --- /dev/null +++ b/docs/core_classes/colourmap.md @@ -0,0 +1,6 @@ +--- +title: morph::ColourMap +layout: page +permalink: /core/colourmap +--- +morph::ColourMap provides a set of colour maps to indicate numerical values with graded colours. \ No newline at end of file diff --git a/docs/core_classes/index.md b/docs/core_classes/index.md new file mode 100644 index 00000000..981eb20e --- /dev/null +++ b/docs/core_classes/index.md @@ -0,0 +1,20 @@ +--- +title: Core maths classes +layout: page +permalink: /core/ +--- +As I developed the data-vis features of morphologica, I found I needed functionality that I've used repeatedly in many programs. +The most basic was a simple mathematical vector class, [morph::vec](/core/vec), which was essential for computing locations within the 3D graphics environment. + +As the project progressed, I developed a number of these classes for handling mathematical operations with a convenient interface: + +* [morph::vec](/core/vec) A mathematical vector class of a fixed size +* [morph::vvec](/core/vvec) A 'variable vector' class +* [morph::mathconst](/core/mathconst) Templated mathematical constants +* [morph::RandUniform](/core/random) Random number generation +* [morph::Scale](/core/scale) A class to scale numbers (log/linear scaling) +* [morph::ColourMap](/core/colourmap) When you visualise, you will need colour maps +* [morph::Matrix22](/core/matrix33) 2x2 matrix operations +* [morph::Matrix33](/core/matrix33) 3x3 matrix operations +* [morph::TransformMatrix](/core/transformmatrix) 4x4 matrix operations are common in graphics systems +* [morph::Quaternion](/core/quaternion) Quaternions are also commonly used for graphics diff --git a/docs/core_classes/range.md b/docs/core_classes/range.md new file mode 100644 index 00000000..e61951f0 --- /dev/null +++ b/docs/core_classes/range.md @@ -0,0 +1,6 @@ +--- +title: morph::range +layout: page +permalink: /core/range +--- +morph::range is a useful little class for specifying a range of values. \ No newline at end of file diff --git a/docs/core_classes/scale.md b/docs/core_classes/scale.md new file mode 100644 index 00000000..461f6289 --- /dev/null +++ b/docs/core_classes/scale.md @@ -0,0 +1,6 @@ +--- +title: morph::Scale +layout: page +permalink: /core/scale +--- +morph::Scale is for scaling numbers. \ No newline at end of file diff --git a/docs/core_classes/vec.md b/docs/core_classes/vec.md new file mode 100644 index 00000000..5cb6a218 --- /dev/null +++ b/docs/core_classes/vec.md @@ -0,0 +1,48 @@ +--- +layout: page +title: morph::vec +permalink: /core/vec/ +--- + +A fixed-size mathematical vector class. Derives from `std::array`. + +```c++ +#include +``` +Create like an `std::array`: + +```c++ +morph::vec v1 = { 1, 2, 3, 4 }; +``` +but you can do maths: + +```c++ +morph::vec v1 = { 1, 2, 3, 4 }; +morph::vec v3 = v1 + v2; // element-wise addition +``` + +It's really useful to be able to do vector maths: + +```c++ +morph::vec u1 = { 1.0f, 0.0f, 0.0f }; +morph::vec u2 = { 0.0f, 1.0f, 0.0f }; +morph::vec u3 = u1.cross (u2); +morph::vec u4 = u1 - u2; +float dp = u1.dot (u3); +``` + +See these programs for more example usage: [tests/testvec](https://github.com/ABRG-Models/morphologica/blob/main/tests/testvec.cpp), [tests/testvecElementOps](https://github.com/ABRG-Models/morphologica/blob/main/tests/testvecElementOps.cpp). + +## Using morph::vec as a key in std::map or within an std::set + +Although morph::vec derives from std::array, you **can't use it as a key in an std::map**. + +```c++ +// Bad! +std::map, myclass> some_map; + +// Also Bad! +std::set> some_set; +``` + +The reason for this is that the less-than operation is redefined, but `std::set` and `std::map` depend upon less-than for their functionality. In std::array, less-than is lexicographic. See this file for a workaround, in which you specify that you want to use morph::vec's lexicographics less-than: [tests/testvec_asmapkey](https://github.com/ABRG-Models/morphologica/blob/main/tests/testvec_asmapkey.cpp). diff --git a/docs/vvec.md b/docs/core_classes/vvec.md similarity index 81% rename from docs/vvec.md rename to docs/core_classes/vvec.md index 476951e8..a420f743 100644 --- a/docs/vvec.md +++ b/docs/core_classes/vvec.md @@ -1,7 +1,7 @@ --- layout: page title: morph::vvec -permalink: /vvec/ +permalink: /core/vvec/ --- This could be a page about the variable vector class vvec. diff --git a/docs/index.md b/docs/index.md index f09f649a..28175b6d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,32 +1,5 @@ --- -title: What is morphologica? +title: morphologica blog layout: home permalink: / --- - -morphologica is a library of header-only C++ code. - -If you're a C++ developer and you want to draw runtime graphs, surface plots or scatter plots that are **fast**, you are a member of the target demographic. - -morphologica provides **simulation support facilities** for simulations of dynamical systems, agent-based models or, in fact, any program that needs dynamic, runtime visualization. - -It helps with: - -* **OpenGL Visualizations of your program while it runs**. A modern OpenGL visualization - scheme called **[morph::Visual](https://github.com/ABRG-Models/morphologica/blob/main/morph/Visual.h)** - provides the ability to visualise 2D and 3D graphs - of surfaces, lines, bars, scatter plots and quiver plots with minimal - processing overhead. - -* **Configuration**: morphologica allows you to easily set up a simulation - parameter configuration system, using the JSON reading and writing - abilities of **[morph::Config](https://github.com/ABRG-Models/morphologica/blob/main/morph/Config.h)**. ([morph::Config Example](https://github.com/ABRG-Models/morphologica/blob/main/examples/jsonconfig.cpp)) - -* **Saving data from your simulation**. morphologica provides a set of - easy-to-use convenience wrappers (**[morph::HdfData](https://github.com/ABRG-Models/morphologica/blob/main/morph/HdfData.h)**) around the HDF5 C - API. By saving data in a standard format, it is easy to access - simulation data in python, MATLAB or Octave for analysis and graphing. ([HdfData Example](https://github.com/ABRG-Models/morphologica/blob/main/examples/hdfdata.cpp)) - -# What is this site for? - -It's to help you to learn how to use the classes in morphologica in your own numerical simulations and data analysis programs. \ No newline at end of file diff --git a/docs/quick.md b/docs/quick.md index 8099b12a..7b15dcd9 100644 --- a/docs/quick.md +++ b/docs/quick.md @@ -2,6 +2,7 @@ title: Quick start layout: page permalink: /quick/ +order: 4 --- Quick-start assumption: You're using a Debian flavour of Linux. If you're using a Mac, see [README.build.mac](https://github.com/ABRG-Models/morphologica/tree/main/README.build.mac.md) for help getting dependencies in place. It's [README.build.windows](https://github.com/ABRG-Models/morphologica/tree/main/README.build.windows.md) for Windows users. diff --git a/docs/who.md b/docs/who.md new file mode 100644 index 00000000..aa3cad3c --- /dev/null +++ b/docs/who.md @@ -0,0 +1,6 @@ +--- +title: Who'd need morphologica? +layout: page +permalink: /who +order: 2 +--- diff --git a/docs/why.md b/docs/why.md new file mode 100644 index 00000000..a6f6ad32 --- /dev/null +++ b/docs/why.md @@ -0,0 +1,19 @@ +--- +title: Why was morphologica developed? +layout: page +permalink: /why +order: 3 +--- +Why expend the time writing an OpenGL visualization system when there are alternatives, like Python's matplotlib already available? + +I think the the answers are 'opportunity', 'preference' and 'benefit'. + +'Opportunity' because I started a project with Stuart Wilson at the University of Sheffield's Department of Psychology in which we were going to solve reaction-diffusion equations and there was a requirement to plot the results of those computations. I had a free hand in how to go about the work and plenty of time on a 4 year project. + +'Preference', because I just don't really like Python very much. I dislike its lack of scope identifiers, which make it awkward to copy blocks of code around and I find the management of Python packages a headache. On the other hand, I do really like C++. + +If the resulting visualization system had not had any promise of showing a benefit over matplotlib or MATLAB, I'd still not have started it and would have lived with the least bad alternative. But vizualization based on computer gaming technology had the promise of being lightning fast with minimal use of computational resources. I really wrote morphologica so that I could have insightful graphics while still getting the most I possilbly could out of the CPU hardware I had access to. + +Could I have used an alternative C++ plotting system? Possibly. Alternatives include CERN's [Root](https://root.cern/), which looked old-fashioned and byzantine, [VTK](https://vtk.org/) from Kitware, which seemed complex to get started with and [matplot++](https://alandefreitas.github.io/matplotplusplus/), which copies the Python matplotlib API which I never got on with! + +What I have ended up with is a library of code which is very easy to incorporate into projects and which can animate 3D plots with very low CPU overhead. It was worth the effort. \ No newline at end of file