Reorganize examples

[henry2004y]

Move examples into docs with WGLMakie support. Handle #71 and #74.

With these changes, each example takes a separate page and generates < 21 MB html file. We won't have outdated demos anymore!

[codecov]

Codecov Report

Merging #77 (a1d67f7) into master (ca04d35) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #77   +/-   ##
=======================================
  Coverage   61.41%   61.41%           
=======================================
  Files           5        5           
  Lines         368      368           
=======================================
  Hits          226      226           
  Misses        142      142           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[TCLiuu]

There is still one issue here, which is the warning in the log.

┌ Warning: cover file doesn't exists
│   cover_path = "/home/runner/work/TestParticle.jl/TestParticle.jl/docs/examples/simulations/../../figures/proton_ganymede_mhdepic.png"
└ @ DemoCards ~/.julia/packages/DemoCards/ZgH8l/src/generate.jl:358

This should be a bug in DemoCards, and I have already submitted the relevant issue.
JuliaDocs/DemoCards.jl#146

[TCLiuu]

Additionally, there is another issue where all the examples have been moved from the 'examples' folder to 'docs', and the dependency has been changed to WGLMakie. The slider on the web version cannot interact properly.

My question is, whether it is necessary to maintain a version of GLMakie for some examples. In my teaching, I directly run the examples and introduce them through interaction.

[TCLiuu]

There is one more strange thing, when running this command on my computer:

julia --project make.jl

There is a strange error in my log, which did not appear in the GitHub action.

Warning: failed to run `@example` block in src/examples/basics/demo_magneticmirror.md:14-109
│ ```@example demo_magneticmirror
│ using JSServe: Page # hide
│ Page(exportable=true, offline=true) # hide
│
│ using TestParticle
│ using TestParticle: getB_mirror
│ using OrdinaryDiffEq
│ using StaticArrays
│ using LinearAlgebra
│ using TestParticleMakie
│ using Printf
│ using WGLMakie
│
│ ### Obtain field
│
│ # Magnetic mirror parameters in SI units
│ const I = 20. # current in the solenoid
│ const N = 45 # number of windings
│ const distance = 10. # distance between solenoids
│ const a = 4.0 # radius of each coil
│
│ function getB(xu)
│    SVector{3}(getB_mirror(xu[1], xu[2], xu[3], distance, a, I*N))
│ end
│...
|...
│ f
│ ```
│   value = UndefVarError: `getB_mirror` not defined
└ @ Documenter.Expanders ~/.julia/packages/Documenter/H5y27/src/Utilities/Utilities.jl:34

Can I trouble you to help test and see if the same error occurs? @henry2004y

[henry2004y]

My question is, whether it is necessary to maintain a version of GLMakie for some examples. In my teaching, I directly run the examples and introduce them through interaction.

Even though all the examples can be run interactively by changing WGLMakie to GLMakie, this may indeed be a problem for users unfamiliar with the plotting packages. Actually you can also find that some of the figures are not interactive after adding the title and labels. For now let's add a note in the front page of the Examples section. I want to avoid demo code duplications.

[henry2004y]

Can I trouble you to help test and see if the same error occurs? @henry2004y

I have a similar issue yesterday. getB_mirror is a recently added method (that lives in master but not in a release patch), so you need to use the master branch of TestParticle to make it work. What I did is

pkg> add TestParticle#master

After we register a new patch this is no longer an issue.

[github-actions]

Benchmark result

Judge result

Benchmark Report for /home/runner/work/TestParticle.jl/TestParticle.jl

Job Properties

• Time of benchmarks:
  • Target: 21 Apr 2023 - 17:31
  • Baseline: 21 Apr 2023 - 17:33
• Package commits:
  • Target: 6b1761
  • Baseline: ca04d3
• Julia commits:
  • Target: 17cfb8
  • Baseline: 17cfb8
• Julia command flags:
  • Target: None
  • Baseline: None
• Environment variables:
  • Target: None
  • Baseline: None

Results

A ratio greater than 1.0 denotes a possible regression (marked with ❌), while a ratio less
than 1.0 denotes a possible improvement (marked with ✅). Only significant results - results
that indicate possible regressions or improvements - are shown below (thus, an empty table means that all
benchmark results remained invariant between builds).

ID	time ratio	memory ratio
["trace", "analytic field", "in place"]	1.16 (5%) ❌	1.00 (1%)

Benchmark Group List

Here's a list of all the benchmark groups executed by this job:

• ["trace", "analytic field"]
• ["trace", "numerical field"]
• ["trace", "time-dependent field"]

Julia versioninfo

Target

Julia Version 1.8.5
Commit 17cfb8e65ea (2023-01-08 06:45 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
      Ubuntu 22.04.2 LTS
  uname: Linux 5.15.0-1035-azure #42-Ubuntu SMP Tue Feb 28 19:41:23 UTC 2023 x86_64 x86_64
  CPU: Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz: 
              speed         user         nice          sys         idle          irq
       #1  2095 MHz       2197 s          0 s        304 s       4320 s          0 s
       #2  2095 MHz       5148 s          0 s        411 s       1246 s          0 s
  Memory: 6.781211853027344 GB (4898.33984375 MB free)
  Uptime: 689.8 sec
  Load Avg:  1.26  1.17  0.78
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, skylake-avx512)
  Threads: 1 on 2 virtual cores

Baseline

Julia Version 1.8.5
Commit 17cfb8e65ea (2023-01-08 06:45 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
      Ubuntu 22.04.2 LTS
  uname: Linux 5.15.0-1035-azure #42-Ubuntu SMP Tue Feb 28 19:41:23 UTC 2023 x86_64 x86_64
  CPU: Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz: 
              speed         user         nice          sys         idle          irq
       #1  2095 MHz       3385 s          0 s        401 s       4344 s          0 s
       #2  2095 MHz       5175 s          0 s        419 s       2515 s          0 s
  Memory: 6.781211853027344 GB (4825.51171875 MB free)
  Uptime: 820.74 sec
  Load Avg:  1.08  1.12  0.82
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, skylake-avx512)
  Threads: 1 on 2 virtual cores

---

Target result

Benchmark Report for /home/runner/work/TestParticle.jl/TestParticle.jl

Job Properties

• Time of benchmark: 21 Apr 2023 - 17:31
• Package commit: 6b1761
• Julia commit: 17cfb8
• Julia command flags: None
• Environment variables: None

Results

Below is a table of this job's results, obtained by running the benchmarks.
The values listed in the ID column have the structure [parent_group, child_group, ..., key], and can be used to
index into the BaseBenchmarks suite to retrieve the corresponding benchmarks.
The percentages accompanying time and memory values in the below table are noise tolerances. The "true"
time/memory value for a given benchmark is expected to fall within this percentage of the reported value.
An empty cell means that the value was zero.

ID	time	GC time	memory	allocations
["trace", "analytic field", "in place"]	9.400 μs (5%)		14.02 KiB (1%)	157
["trace", "analytic field", "out of place"]	6.950 μs (5%)		12.31 KiB (1%)	133
["trace", "numerical field", "in place"]	24.601 μs (5%)		27.08 KiB (1%)	175
["trace", "numerical field", "out of place"]	20.801 μs (5%)		21.45 KiB (1%)	147
["trace", "time-dependent field", "in place"]	10.100 μs (5%)		15.22 KiB (1%)	172
["trace", "time-dependent field", "out of place"]	8.601 μs (5%)		13.52 KiB (1%)	148

Benchmark Group List

Here's a list of all the benchmark groups executed by this job:

• ["trace", "analytic field"]
• ["trace", "numerical field"]
• ["trace", "time-dependent field"]

Julia versioninfo

Julia Version 1.8.5
Commit 17cfb8e65ea (2023-01-08 06:45 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
      Ubuntu 22.04.2 LTS
  uname: Linux 5.15.0-1035-azure #42-Ubuntu SMP Tue Feb 28 19:41:23 UTC 2023 x86_64 x86_64
  CPU: Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz: 
              speed         user         nice          sys         idle          irq
       #1  2095 MHz       2197 s          0 s        304 s       4320 s          0 s
       #2  2095 MHz       5148 s          0 s        411 s       1246 s          0 s
  Memory: 6.781211853027344 GB (4898.33984375 MB free)
  Uptime: 689.8 sec
  Load Avg:  1.26  1.17  0.78
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, skylake-avx512)
  Threads: 1 on 2 virtual cores

---

Baseline result

Benchmark Report for /home/runner/work/TestParticle.jl/TestParticle.jl

Job Properties

• Time of benchmark: 21 Apr 2023 - 17:33
• Package commit: ca04d3
• Julia commit: 17cfb8
• Julia command flags: None
• Environment variables: None

Results

Below is a table of this job's results, obtained by running the benchmarks.
The values listed in the ID column have the structure [parent_group, child_group, ..., key], and can be used to
index into the BaseBenchmarks suite to retrieve the corresponding benchmarks.
The percentages accompanying time and memory values in the below table are noise tolerances. The "true"
time/memory value for a given benchmark is expected to fall within this percentage of the reported value.
An empty cell means that the value was zero.

ID	time	GC time	memory	allocations
["trace", "analytic field", "in place"]	8.100 μs (5%)		14.02 KiB (1%)	157
["trace", "analytic field", "out of place"]	6.850 μs (5%)		12.31 KiB (1%)	133
["trace", "numerical field", "in place"]	24.501 μs (5%)		27.08 KiB (1%)	175
["trace", "numerical field", "out of place"]	20.501 μs (5%)		21.45 KiB (1%)	147
["trace", "time-dependent field", "in place"]	10.501 μs (5%)		15.22 KiB (1%)	172
["trace", "time-dependent field", "out of place"]	8.400 μs (5%)		13.52 KiB (1%)	148

Benchmark Group List

Here's a list of all the benchmark groups executed by this job:

• ["trace", "analytic field"]
• ["trace", "numerical field"]
• ["trace", "time-dependent field"]

Julia versioninfo

Julia Version 1.8.5
Commit 17cfb8e65ea (2023-01-08 06:45 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
      Ubuntu 22.04.2 LTS
  uname: Linux 5.15.0-1035-azure #42-Ubuntu SMP Tue Feb 28 19:41:23 UTC 2023 x86_64 x86_64
  CPU: Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz: 
              speed         user         nice          sys         idle          irq
       #1  2095 MHz       3385 s          0 s        401 s       4344 s          0 s
       #2  2095 MHz       5175 s          0 s        419 s       2515 s          0 s
  Memory: 6.781211853027344 GB (4825.51171875 MB free)
  Uptime: 820.74 sec
  Load Avg:  1.08  1.12  0.82
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, skylake-avx512)
  Threads: 1 on 2 virtual cores

---

Runtime information

Runtime Info
BLAS #threads	1
BLAS.vendor()	openblas64
Sys.CPU_THREADS	2

lscpu output:

Architecture:                    x86_64
CPU op-mode(s):                  32-bit, 64-bit
Address sizes:                   46 bits physical, 48 bits virtual
Byte Order:                      Little Endian
CPU(s):                          2
On-line CPU(s) list:             0,1
Vendor ID:                       GenuineIntel
Model name:                      Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz
CPU family:                      6
Model:                           85
Thread(s) per core:              1
Core(s) per socket:              2
Socket(s):                       1
Stepping:                        4
BogoMIPS:                        4190.38
Flags:                           fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl xtopology cpuid pni pclmulqdq ssse3 fma cx16 pcid sse4_1 sse4_2 movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch invpcid_single pti fsgsbase bmi1 hle avx2 smep bmi2 erms invpcid rtm mpx avx512f avx512dq rdseed adx smap clflushopt avx512cd avx512bw avx512vl xsaveopt xsavec xsaves md_clear
Hypervisor vendor:               Microsoft
Virtualization type:             full
L1d cache:                       64 KiB (2 instances)
L1i cache:                       64 KiB (2 instances)
L2 cache:                        2 MiB (2 instances)
L3 cache:                        35.8 MiB (1 instance)
NUMA node(s):                    1
NUMA node0 CPU(s):               0,1
Vulnerability Itlb multihit:     KVM: Mitigation: VMX unsupported
Vulnerability L1tf:              Mitigation; PTE Inversion
Vulnerability Mds:               Mitigation; Clear CPU buffers; SMT Host state unknown
Vulnerability Meltdown:          Mitigation; PTI
Vulnerability Mmio stale data:   Vulnerable: Clear CPU buffers attempted, no microcode; SMT Host state unknown
Vulnerability Retbleed:          Vulnerable
Vulnerability Spec store bypass: Vulnerable
Vulnerability Spectre v1:        Mitigation; usercopy/swapgs barriers and __user pointer sanitization
Vulnerability Spectre v2:        Mitigation; Retpolines, STIBP disabled, RSB filling, PBRSB-eIBRS Not affected
Vulnerability Srbds:             Not affected
Vulnerability Tsx async abort:   Mitigation; Clear CPU buffers; SMT Host state unknown

Cpu Property	Value
Brand	Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz
Vendor	:Intel
Architecture	:Skylake
Model	Family: 0x06, Model: 0x55, Stepping: 0x04, Type: 0x00
Cores	2 physical cores, 2 logical cores (on executing CPU)
	No Hyperthreading hardware capability detected
Clock Frequencies	Not supported by CPU
Data Cache	Level 1:3 : (32, 1024, 36608) kbytes
	64 byte cache line size
Address Size	48 bits virtual, 46 bits physical
SIMD	512 bit = 64 byte max. SIMD vector size
Time Stamp Counter	TSC is accessible via rdtsc
	TSC increased at every clock cycle (non-invariant TSC)
Perf. Monitoring	Performance Monitoring Counters (PMC) are not supported
Hypervisor	Yes, Microsoft

[TCLiuu]

I found that there are some display issues with Democards. This is how it looks in the version I generated locally.

It is different from the version of the documentation of Democards with theme "grid". This should not be a problem with my network causing the CSS to not load correctly. May I ask if your local version has the same issue?

[henry2004y]

I have the same issue, which does not happen for my other package Vlasiator demo. Based on a quick scan the json files are identical...

Maybe we can ignore that for now, leave an issue and fix it later.