Examples#
Below you will find a series of examples demonstrating how to use mapflpy for various basic use cases.
Getting Started#
The following examples demonstrate how to use the standalone tracing functions provided
in the scripts module. These functions act as simple wrappers around the
core tracing functionality of the TracerMP class, allowing users
to perform “one-off” tracing calls without having to manage _Tracer
subclasses.
These examples – and the the corresponding functions in scripts – are suitable
for most common use cases, and can be used as a starting point for more complex applications.
Using the Tracer Class#
If you need more control over the tracing process, you can use the Tracer
class directly. As mentioned throughout these examples, the Tracer class
enforces a singleton pattern to manage issues that arise from the underlying mapflpy_fortran object
not being thread-safe. As a result, it is recommended to use the Tracer class
in single-threaded contexts only viz. instantiating one instance of the class at a time.
The benefit of using the Tracer class directly is that it provides direct
access to the mapflpy_fortran object – allowing for faster and more flexible tracing operations.
Alternatively, the TracerMP (while thread-safe) branches new instances of the
mapflpy_fortran object into discrete processes and communicates with these instances through
python’s Pipe() protocol. Although this approach is more robust in multi-threaded
contexts, it incurs a performance penalty due to the overhead of inter-process communication.
Using the TracerMP Class#
The TracerMP class is a multi-processing, thread-safe variant of the
Tracer class. It enables users to create multiple (distinct) instances of the
mapflpy_fortran object in separate processes, allowing for concurrent tracing operations
across multiple threads. the TracerMP branches new instances of the
mapflpy_fortran object into discrete processes and communicates with these instances through
python’s Pipe() protocol.
The Pipe() protocol requires that
the multiprocessing.connection.Connection is properly opened and closed to
avoid resource leaks. Therefore, it is recommended to use the TracerMP
class within a context manager (the with statement) to ensure that resources are
properly managed (or, alternatively, one can explicitly open and close the connection using the
connect() and disconnect() methods).
Advanced Examples#
This final section is aimed at exploring more involved visualization approaches using e.g. interdomain tracing and
fieldline polarity filtering. The accompanying utility functions (i.e. utils) will be catalogued
here in future releases of the mapflpy documentation.
