flamegpu / flamegpu2-docs Goto Github PK

The visualisation docs are very sparse, and need completing.

Agent Input / Output / Logging docs are partial with several TODO statements that need completing.

This requires a custom reduction (assuming it works). Will be documented once tested as part of PRIMAGE.

Building on CI currently does not error on warnigns. Some of these warnigns should be errors ideally, due to the auto-generated nature of parts of the docs this is impractical to fix / a low priority.

At some point, it would be good to make the build CI fail on (at least some of) the warnings being output, and resolve as many as possible.

This PR introduces agent id, will require documenting. Here's a brief summary of relevant info.

Had a brief look at docs master, but wasn't clear about the best way to fit the relevant info from this in.

Intro

Agents all contain an internal variable representing a unique identifier for the agent. This is automatically managed by FLAMEGPU2. IDs are assigned to agents at the start of a simulation, or at birth when new agents are created during the simulation. There is no method to change an agent's ID during a simulation's execution.

How IDs are handled at import/export

If agents with IDs are exported from a CUDASimulation to file or an AgentVector, their IDs will be retained when re-imported. If an ID conflict is detected when importing agents, an AgentIDCollision exception will be thrown. This can be resolved by using AgentVector::resetAllIDs() or AgentVector::Agent::resetID(), which will return IDs to an uninitialised state.

It is not currently possible to programmatically reset IDs when importing agents from file (as they cannot be loaded directly to an AgentVector). Therefore it is necessary to manually modify the xml or json file to replace any conflicting IDs.

Accessing agent IDs

Agent IDs can be accessed with the getID() method in all places where accessing an agent variable is possible (AgentVector::Agent, DeviceAPI, DeviceAPI::AgentOut, DeviceAgentVector, HostNewAgentAPI).

Type of ID

Within the C and CUDA interfaces the type of IDs is id_t, which likely maps to unsigned int. However, this may be mapped to other types in special builds which require a greater ID range. Within the python interface it is possible to add/use variables of id_t to messages, environment etc with newVariableID(). This will then update if someone rebuilds pyflamegpu with a different sized unsigned for IDs.

Checking for init ID

Agents which have not had their ID initialised will have and ID value of ID_NOT_SET (This is currently for internal usage, so may not be accessible via Python, but it evaluates to 0 and if changes will break alot of stuff.)

Submodels

Agents bound to a submodel will always have their ID bound to the submodel.

Agents within a submodel that are unbound, and therefore recreated each time the submodel is executed may have the same IDs between runs of the submodel, however this cannot be guaranteed so should not be relied on.

Document Bucket Messaging

There doesn't appear to be any detail for the Random APIs in the documentation.

Required

• HostAPI
• DeviceAPI

Clear Installation instructions are needed and readily avaialble.

• C++/CUDA
  • Binary from github release
  • From source
  • Docker?
• Python
  • Binary from github release whl.
  • From source
  • Docker?
  • Recommend the use of venvs when isntalling from whl/source.

Pre-requisite dependencies will need listing for each platform for each install method?

If visusalisation is the only option for binaries then additional steps may be required.

Array messagings now (soon) make 2 iterators avialable, a non-wrapped iterator by default, and a specialised wrapping iterator (in all dimensions) via .wrap. This change needs to be documented.

See FLAMEGPU/FLAMEGPU2#549

https://docs.flamegpu.com/guide/2-model-definition/2-environment.html

This block should be;

# Define environmental properties and their initial values
env.newPropertyFloat("f_prop", 12.0)              # Create float property 'f_prop', with value of 12
env.newPropertyArrayInt("ia_prop", 3, [1, 2, 3])  # Create int array property 'ia_prop', with value of [1, 2, 3]
env.newPropertyChar("c_prop", 'g', True)          # Create constant char property 'c_prop', with value 'g'

There are many issues in this code block (I'm not even sure about python type conversion for chars, cc @MILeach

Noticed by Carlos.

Visisble TODO comment moved to this issue.

TODO: annotated source code image with sections identified

in src/guide/1-meta/3-structure.rst

Usage of FLAMEGPU_DEVICE_FUNCTION and other utility function macros is not yet documented. Carlos had to clarify their usage via the Python API (as he found in James's PredPrey python version).

These are not particularly clear in the RTC version, where they have to be included with every agent function that will use them, rather than declared at global scope.

They're defined at the end of this file: https://github.com/FLAMEGPU/FLAMEGPU2/blob/master/include/flamegpu/runtime/AgentFunction_shim.h

Submodel docs could do with some expansion.

Needs python example(s).

Init / Step / Exit function and exit condition docs do not show how to use callback functions, instead only the CUDA C++ version is fully documented.

The API docs generate a number of binary files which appear to change significantly between releases, adding bloat to the repository.

It might be worth tweaking the deploy CI to start from a fresh gh-pages branch and force pushing, to avoid the repository growing unneccesarily large.

Alternatively Adjusting the doxygen setup might be worthwhile.

1. pip install

sphinx>=2.0
breathe>=4.13.0
exhale
sphinx_rtd_theme

2. sphinx-quickstart

3. Tweak quick start files to add in exhale config

4. make html

5. push to RTD?

Step 1, Make auto install/check available
Step 2 & 3, run once locally commit to this repo
Step 4, Update CMake in main fgpu2 dev repo to target this (quickstart gets make.bat and makefile so simple CMake command make html should suffice)
conf.py will need to be updated to direct to doxygen output.

  breathe_projects = {
    "FLAME GPU 2": "./xml"
  }

Currenlty C++ API docs are generated and hosted by CI in this repo, but this does not include any docs for pyflamegpu.

This is dependent upon the pyflamegpu docs being possible on the main repo in the first place (FLAMEGPU/FLAMEGPU2#455)

It will also probably require the pyflamegpu target to be built (or possibly a sub target) and therfore require CUDA to be installed on the CI (without very significant changes to CMake)

Several sections require additional python examples.

Including (but possibly not limited to):

• Ensembles

TODO: Diagram demonstrating messaging structure

From src/guild/3-behaviour-definition/4-agent-communication.rst

We should protect master so that CI must pass before things can be merged / committed to it, as th CI then publishses the contents of this branch to gh-pages.

This will mean that we have to use PRs to get content into master, which will slow down rapid fixes, so probably better to do this once the docs are in a more complete state.

It would be nice if we can also prevent the gh-pages branch being deleted or PRs being made against it (not sure if possible, although we could make ci fail (and therefore block merging via a branch protection rule)

Identified this as missing from this discussion.

My answer there is a very rough draft of the structure. It would obviously require clearer examples.

Proposed Structure

• Help! How do I debug/validate my model?
  • Runtime Error Checking: What is Seatbelts? (This page already exists in isolation, might need a little tweaking to fit the new flow)
  • printf() (This is a fairly straight forward page, with a few examples)
  • Logging, this will mostly link back to the logging docs pages, but can provide some additional usage examples e.g. env macro property counters.
  • CUDA debugging. This would involve more images, and require some O/S specific stuff. Also need to do some testing/experimentation regarding Python debugging.

The current url structure https://docs.flamegpu.com/guide/1-meta/2-creating-project.html is probably not ideal from an SEO perspective, and changing urls will break any bookmarks people make so sooner is probably better than later to change them.

I.e the 1-meta directory should probably just be first-steps or similar. This will make the order of directories on disk not match the order in the navigation, but grand scheme that's not an issue.

This is currently just the ToC, but should probbaly have some introductory text.

We should document the releases available, where to access them and what the changelog(s) are if any. Possibly only if the root FLAMEGPU2 repo has been found / made available.

A simple getting started page should be provided, walking users through creating a new model based on the template repository.

We should probably (eventually?) provided getting started guides for C++/RTC, and Python.

Broken :ref in the tutorial index in the Configuring CMake section.

A more detailed guide, regarding building FLAME GPU 2 from source can be found :ref:`here<q-compiling flamegpu>`.

https://docs.flamegpu.com/tutorial/index.html#configuring-cmake

Update c++ examples to include the use of the flamegpu:: namespace (once FLAMEGPU/FLAMEGPU2#551 is merged)

There should probably be some coverage of timing.

• Performance trouble shooting should reference how timing can be collected within FGPU2.
• Timing/performance metrics should be detailed in logging pages (emphasis perf metrics always logged in ensembles??).
• Maybe some advanced discussion regarding accuracy/wddm, impact of cuda event timers etc.

The current docs is missing a guide for HostAPI functionality.

Simple page/section aimed at Python users explaining the CUDA C equivalent of common syntax vs python which they may need for defining agent functions.

E.g, defining variable, if-else, for, function define/call.

Could link to an external guide/s at the end for greater detail.

For a complete list of supported types, see TODO: reference page for available types.

From 2-model-definition/3-agent.rst: Agent Variables

In a number of places (atleast 6) there are links intending to link to API docs, which do not do so.

The ones i've found are of the pattern:

Full API documentation for the ``X``: link

Where X is the name of a class, such aas EnvironmentDescription.

We could hardcode links to the hosted API docs, but this feels brittle. There should be a breathe/exhale way of finding the correct link, although I'm not sure exactly how.

Additionally, as the api docs are an optional part of the docs project, these links will only exist if the API docs are being built, which is (suprisingly) expensive in terms or time.

• src/guide/6-agent-birth-death/1-agent-birth-device.rst:149
• src/guide/6-agent-birth-death/3-agent-death.rst:53
• src/guide/2-model-definition/3-agent.rst:152
• src/guide/2-model-definition/2-environment.rst:137
• src/guide/2-model-definition/1-model.rst:31
• src/guide/3-behaviour-definition/1-defining-agent-functions.rst:170

Everywhere flamegpu2 uses atomics (and possibly some cub/thrust), has the potential for non-determinism.

This should be clearly documented in the user guide, with any suggested workaround (e.g. if we eventually add a DETERMINISTIC CMake flag).

Files generated during building are currently placed into the src directory, not the current binary directory.

This is bad for out of tree builds, but sphinx/breathe/exhale does not make this easy to fix, as the api directory must be a child of the sphinx source directory.

In practice to resolve this, sphinx files will need copying into the build directory at build time (configure would not be good enough) but that feels like it will have overheads / be painful.

It might also be good to use cmake to generate index.rst, so the inclusion of api/library_root can be set according to the CMake varaible / location of the api directory.

Most users are expected to run simulations via simulate().

Alternatively, users can use step() manually, to run simulations step by step themselves, however they must then also handle other parts of the typical simulation themselves:

• Init functions will not be executed for them. They must call CUDASimulation::initFunctions() themselves.
• Any Logging from a previous Simulate() will exist, unless they call CUDASimulation::resetLog()
• step() returns a boolean, set to true if the simulation loop is expected to continue, and false if any Exit Condition returned flamegpu::EXIT. It is up to the user to deal with this.
• The user will/may need to call processStepLog after the last step they intend to run.
• Exit functions will not be exectued for them, they must call CUDASimulation::exitFunctions().
  • Exit function logging will also need to be explicitly processed, via processExitLog
• If they wish export logs to disk, they need to call exportLog as appropriate.

I.e. they need to handle anything in simulate().

There are also several things that will not work.

• The Simulation time will not be recorded, and timing from any previous calls to simulate() on the same instance may be present / accessible.
• There is potential for bugs if anything is too strongly assuming that simulate is the only option (per step allocations perhaps)

As this is not the intended / typical way users are expected to run simulations, it should be marked as such in some way.

Use of indentation across differnt files varies between 2 and 4 spaces, and sometimes is a mix.

We should try to standardise this (I'm not sure what the "correct" values is for this rst extension without looking)

The same also applies to if there should be a blank line prior to any code or not.

This doesn't appear to currently be documented.

At least not in Python 3.10. See sphinx-doc/sphinx#9562

Can fix by enforcing newer Sphinx version. E.g. 5.x

We can enforce HTTPS via github settings.

This should be done for this repo and for the main repo.

Inspired by: FLAMEGPU/FLAMEGPU2#797

Have now added support: FLAMEGPU/FLAMEGPU2#801

Absent from defining messages page.

https://docs.flamegpu.com/guide/defining-messages-communication/index.html

As the number of messaging docs has grown, the splitting of output / input examples for each type seems less ideal / it is less clear how to use both input and output for a given type.

Instead I propose:

1. A general description of messaging
   1. Include general output and general input instructions, with bruteforce as the examples
2. A table of the availabel types, with links to subsequent sections
3. For each messaging type:
   • Describe the shcheme and when it is appropriate for use / why it is a different type.
   • Demonstrate defining the message description in C++ and python
   • Demonstrate output (agent functions are all CUDA C++)
   • Demonstrate input (agent functions are all CUDA C++). Include variants such as .wrap() where appropriate

Once issues with breeze have been resolved we should be able to include the API docs in the hosted userguide (via breeze).

The main issue will be that the published docs are only updated when this repo is updated, rather than the FLAMEGPU/FLAMEGPU2 repo

This will renaming everywhere mentioned.

e.g. https://github.com/FLAMEGPU/FLAMEGPU2-docs/blob/master/src/guide/3-behaviour-definition/1-defining-functions.rst

  .. code-tab:: python

    # Define an agent function called agent_fn1
    agent_fn1_source = """
    FLAMEGPU_AGENT_FUNCTION(agent_fn1, MsgNone, MsgNone) {
        # Behaviour goes here
    }
    """

Should become

 .. code-tab:: python

   # Define an agent function called agent_fn1
   agent_fn1_source = r"""
   FLAMEGPU_AGENT_FUNCTION(agent_fn1, MsgNone, MsgNone) {
       # Behaviour goes here
   }
   """

Accessing an environment variable array, doesn't require array length as template argument?

Agent variable arrays do.

(I think paul was also concerned that environment is get whilst agents are getVariable.

Need to adjust the theme to be clearly FLAME GPU 2, and match the website.

It may be possible to embed more interactive Python content with the Jupyter extension,

https://jupyter-sphinx.readthedocs.io/en/latest/

e.g. https://ipygany.readthedocs.io/en/latest/usage.html

• Semver, release versioning
• FLAMEGPU_VERSION macro, such as 2001004 which encodes 2.1.4. Does not include pre-release or build info (as these are alphanumeric).
• flamegpu::VERSION_MAJOR and pyflamegpu.VERSION_MAJOR
• flamegpu::VERSION_MINOR and pyflamegpu.VERSION_MINOR
• flamegpu::VERSION_PATCH and pyflamegpu.VERSION_PATCH
• flamegpu::VERSION_PRERELEASE and pyflamegpu.VERSION_PRERELEASE
• flamegpu::VERSION_BUILDMETADATA and pyflamegpu.VERSION_BUILDMETADATA
• flamegpu::VERSION_STRING and pyflamegpu.VERSION_STRING
• flamegpu::VERSION_FULL and pyflamegpu.VERSION_FULL

Depends on FLAMEGPU/FLAMEGPU2#596

The tutorial pages include partial code blocks to show only the relevant snippets of code.

This means that in some cases, the code blocks are not valid python (or c++/cuda?) on their own.

I.e. the following highlights the wrong segment as a string, due to the missing opening """

Only a single code block fails to parse via pygments entriely, generating a warning and is not highligted.

Additionally, (in my opinion) the elipses indicating there is more code above below are unclear, and combined with snippets with mismatched braces aren't the easiest to read/follow in isolation