conf
¶
Loading a configuration¶
Various aspects of PyPhi’s behavior can be configured.
When PyPhi is imported, it checks for a YAML file named pyphi_config.yml
in
the current directory and automatically loads it if it exists; otherwise the
default configuration is used.
The various settings are listed here with their defaults.
>>> import pyphi
>>> defaults = pyphi.config.defaults()
Print the config
object to see the current settings:
>>> print(pyphi.config)
{ 'ASSUME_CUTS_CANNOT_CREATE_NEW_CONCEPTS': False,
'CACHE_SIAS': False,
'CACHE_POTENTIAL_PURVIEWS': True,
'CACHING_BACKEND': 'fs',
...
Setting can be changed on the fly by assigning them a new value:
>>> pyphi.config.PROGRESS_BARS = False
It is also possible to manually load a configuration file:
>>> pyphi.config.load_config_file('pyphi_config.yml')
Or load a dictionary of configuration values:
>>> pyphi.config.load_config_dict({'PRECISION': 1})
Approximations and theoretical options¶
These settings control the algorithms PyPhi uses.
Parallelization and system resources¶
These settings control how much processing power and memory is available for PyPhi to use. The default values may not be appropriate for your use-case or machine, so please check these settings before running anything. Otherwise, there is a risk that simulations might crash (potentially after running for a long time!), resulting in data loss.
-
Warning
Only one of
PARALLEL_CONCEPT_EVALUATION
,PARALLEL_CUT_EVALUATION
, andPARALLEL_COMPLEX_EVALUATION
can be set toTrue
at a time. For maximal efficiency, you should parallelize the highest level computations possible, e.g., parallelize complex evaluation instead of cut evaluation, but only if you are actually computing a complex. You should only parallelize concept evaluation if you are just computing aCauseEffectStructure
.
Memoization and caching¶
PyPhi provides a number of ways to cache intermediate results.
Logging¶
These settings control how PyPhi handles log messages. Logs can be written to standard output, a file, both, or none. If these simple default controls are not flexible enough for you, you can override the entire logging configuration. See the documentation on Python’s logger for more information.
The config
API¶
-
class
pyphi.conf.
Option
(default, values=None, on_change=None, doc=None) A descriptor implementing PyPhi configuration options.
Parameters: default – The default value of this
Option
.Keyword Arguments: - values (list) – Allowed values for this option. A
ValueError
will be raised ifvalues
is notNone
and the option is set to be a value not in the list. - on_change (function) – Optional callback that is called when the value
of the option is changed. The
Config
instance is passed as the only argument to the callback. - doc (str) – Optional docstring for the option.
- values (list) – Allowed values for this option. A
-
class
pyphi.conf.
ConfigMeta
(cls_name, bases, namespace) Metaclass for
Config
.Responsible for setting the name of each
Option
when a subclass ofConfig
is created; becauseOption
objects are defined on the class, not the instance, their name should only be set once.Python 3.6 handles this exact need with the special descriptor method
__set_name__
(see PEP 487). We should use that once we drop support for 3.4 & 3.5.
-
class
pyphi.conf.
Config
Base configuration object.
See
PyphiConfig
for usage.-
classmethod
options
() Return a dictionary the
Option
objects for this config
-
defaults
() Return the default values of this configuration.
-
load_config_dict
(dct) Load a dictionary of configuration values.
-
load_config_file
(filename) Load config from a YAML file.
-
snapshot
() Return a snapshot of the current values of this configuration.
-
override
(**new_values) Decorator and context manager to override configuration values.
The initial configuration values are reset after the decorated function returns or the context manager completes it block, even if the function or block raises an exception. This is intended to be used by tests which require specific configuration values.
Example
>>> from pyphi import config >>> @config.override(PRECISION=20000) ... def test_something(): ... assert config.PRECISION == 20000 ... >>> test_something() >>> with config.override(PRECISION=100): ... assert config.PRECISION == 100 ...
-
classmethod
-
pyphi.conf.
configure_logging
(conf) Reconfigure PyPhi logging based on the current configuration.
-
class
pyphi.conf.
PyphiConfig
pyphi.config
is an instance of this class.-
ASSUME_CUTS_CANNOT_CREATE_NEW_CONCEPTS
default=False
In certain cases, making a cut can actually cause a previously reducible concept to become a proper, irreducible concept. Assuming this can never happen can increase performance significantly, however the obtained results are not strictly accurate.
-
CUT_ONE_APPROXIMATION
default=False
When determining the MIP for \(\Phi\), this restricts the set of system cuts that are considered to only those that cut the inputs or outputs of a single node. This restricted set of cuts scales linearly with the size of the system; the full set of all possible bipartitions scales exponentially. This approximation is more likely to give theoretically accurate results with modular, sparsely-connected, or homogeneous networks.
-
MEASURE
default='EMD'
The measure to use when computing distances between repertoires and concepts. Users can dynamically register new measures with the
pyphi.distance.measures.register
decorator; seedistance
for examples. A full list of currently installed measures is available by callingprint(pyphi.distance.measures.all())
. Note that some measures cannot be used for calculating \(\Phi\) because they are asymmetric.
-
PARALLEL_CONCEPT_EVALUATION
default=False
Controls whether concepts are evaluated in parallel when computing cause-effect structures.
-
PARALLEL_CUT_EVALUATION
default=True
Controls whether system cuts are evaluated in parallel, which is faster but requires more memory. If cuts are evaluated sequentially, only two
SystemIrreducibilityAnalysis
instances need to be in memory at once.
-
PARALLEL_COMPLEX_EVALUATION
default=False
Controls whether systems are evaluated in parallel when computing complexes.
-
NUMBER_OF_CORES
default=-1
Controls the number of CPU cores used to evaluate unidirectional cuts. Negative numbers count backwards from the total number of available cores, with
-1
meaning ‘use all available cores.’
-
MAXIMUM_CACHE_MEMORY_PERCENTAGE
default=50
PyPhi employs several in-memory caches to speed up computation. However, these can quickly use a lot of memory for large networks or large numbers of them; to avoid thrashing, this setting limits the percentage of a system’s RAM that the caches can collectively use.
-
CACHE_SIAS
default=False
PyPhi is equipped with a transparent caching system for
SystemIrreducibilityAnalysis
objects which stores them as they are computed to avoid having to recompute them later. This makes it easy to play around interactively with the program, or to accumulate results with minimal effort. For larger projects, however, it is recommended that you manage the results explicitly, rather than relying on the cache. For this reason it is disabled by default.
-
CACHE_REPERTOIRES
default=True
PyPhi caches cause and effect repertoires. This greatly improves speed, but can consume a significant amount of memory. If you are experiencing memory issues, try disabling this.
-
CACHE_POTENTIAL_PURVIEWS
default=True
Controls whether the potential purviews of mechanisms of a network are cached. Caching speeds up computations by not recomputing expensive reducibility checks, but uses additional memory.
-
CLEAR_SUBSYSTEM_CACHES_AFTER_COMPUTING_SIA
default=False
Controls whether a
Subsystem
’s repertoire and MICE caches are cleared withclear_caches()
after computing theSystemIrreducibilityAnalysis
. If you don’t need to do any more computations after runningsia()
, then enabling this may help conserve memory.
-
CACHING_BACKEND
default='fs'
Controls whether precomputed results are stored and read from a local filesystem-based cache in the current directory or from a database. Set this to
'fs'
for the filesystem,'db'
for the database.
-
FS_CACHE_VERBOSITY
default=0
Controls how much caching information is printed if the filesystem cache is used. Takes a value between
0
and11
.
-
FS_CACHE_DIRECTORY
default='__pyphi_cache__'
If the filesystem is used for caching, the cache will be stored in this directory. This directory can be copied and moved around if you want to reuse results e.g. on a another computer, but it must be in the same directory from which Python is being run.
-
MONGODB_CONFIG
default={'port' -- 27017, 'database_name' -- 'pyphi', 'host': 'localhost', 'collection_name': 'cache'}
Set the configuration for the MongoDB database backend (only has an effect if
CACHING_BACKEND
is'db'
).
-
REDIS_CACHE
default=False
Specifies whether to use Redis to cache
MaximallyIrreducibleCauseOrEffect
.
-
REDIS_CONFIG
default={'port' -- 6379, 'host' -- 'localhost'}
Configure the Redis database backend. These are the defaults in the provided
redis.conf
file.
-
LOG_FILE
default='pyphi.log'
,on_change=configure_logging
Controls the name of the log file.
-
LOG_FILE_LEVEL
default='INFO'
,on_change=configure_logging
Controls the level of log messages written to the log file. This setting has the same possible values as
LOG_STDOUT_LEVEL
.
-
LOG_STDOUT_LEVEL
default='WARNING'
,on_change=configure_logging
Controls the level of log messages written to standard output. Can be one of
'DEBUG'
,'INFO'
,'WARNING'
,'ERROR'
,'CRITICAL'
, orNone
.'DEBUG'
is the least restrictive level and will show the most log messages.'CRITICAL'
is the most restrictive level and will only display information about fatal errors. If set toNone
, logging to standard output will be disabled entirely.
-
LOG_CONFIG_ON_IMPORT
default=True
Controls whether the configuration is printed when PyPhi is imported.
Tip
If this is enabled and
LOG_FILE_LEVEL
isINFO
or higher, then the log file can serve as an automatic record of which configuration settings you used to obtain results.
-
PROGRESS_BARS
default=True
Controls whether to show progress bars on the console.
Tip
If you are iterating over many systems rather than doing one long-running calculation, consider disabling this for speed.
-
PRECISION
default=6
If
MEASURE
isEMD
, then the Earth Mover’s Distance is calculated with an external C++ library that a numerical optimizer to find a good approximation. Consequently, systems with analytically zero \(\Phi\) will sometimes be numerically found to have a small but non-zero amount. This setting controls the number of decimal places to which PyPhi will consider EMD calculations accurate. Values of \(\Phi\) lower than10e-PRECISION
will be considered insignificant and treated as zero. The default value is about as accurate as the EMD computations get.
-
VALIDATE_SUBSYSTEM_STATES
default=True
Controls whether PyPhi checks if the subsystems’s state is possible (reachable with nonzero probability from some previous state), given the subsystem’s TPM (which is conditioned on background conditions). If this is turned off, then calculated \(\Phi\) values may not be valid, since they may be associated with a subsystem that could never be in the given state.
-
VALIDATE_CONDITIONAL_INDEPENDENCE
default=True
Controls whether PyPhi checks if a system’s TPM is conditionally independent.
-
SINGLE_MICRO_NODES_WITH_SELFLOOPS_HAVE_PHI
default=False
If set to
True
, the \(\Phi\) value of single micro-node subsystems is the difference between their unpartitionedCauseEffectStructure
(a single concept) and the null concept. If set to False, their \(\Phi\) is defined to be zero. Single macro-node subsystems may always be cut, regardless of circumstances.
-
REPR_VERBOSITY
default=2
,values=[0, 1, 2]
Controls the verbosity of
__repr__
methods on PyPhi objects. Can be set to0
,1
, or2
. If set to1
, callingrepr
on PyPhi objects will return pretty-formatted and legible strings, excluding repertoires. If set to2
,repr
calls also include repertoires.Although this breaks the convention that
__repr__
methods should return a representation which can reconstruct the object, readable representations are convenient since the Python REPL callsrepr
to represent all objects in the shell and PyPhi is often used interactively with the REPL. If set to0
,repr
returns more traditional object representations.
-
PRINT_FRACTIONS
default=True
Controls whether numbers in a
repr
are printed as fractions. Numbers are still printed as decimals if the fraction’s denominator would be large. This only has an effect ifREPR_VERBOSITY > 0
.
-
PARTITION_TYPE
default='BI'
,values=['BI', 'TRI', 'ALL']
Controls the type of partition used for \(\varphi\) computations.
If set to
'BI'
, partitions will have two parts.If set to
'TRI'
, partitions will have three parts. In addition, computations will only consider partitions that strictly partition the mechanism the mechanism. That is, for the mechanism(A, B)
and purview(B, C, D)
the partition:A,B ∅ ─── ✕ ─── B C,D
is not considered, but:
A B ─── ✕ ─── B C,D
is. The following is also valid:
A,B ∅ ─── ✕ ───── ∅ B,C,D
In addition, this setting introduces “wedge” tripartitions of the form:
A B ∅ ─── ✕ ─── ✕ ─── B C D
where the mechanism in the third part is always empty.
In addition, in the case of a \(\varphi\)-tie when computing a
MaximallyIrreducibleCause
orMaximallyIrreducibleEffect
, The'TRIPARTITION'
setting choses the MIP with smallest purview instead of the largest (which is the default).Finally, if set to
'ALL'
, all possible partitions will be tested.
-
PICK_SMALLEST_PURVIEW
default=False
When computing a
MaximallyIrreducibleCause
orMaximallyIrreducibleEffect
, it is possible for several MIPs to have the same \(\varphi\) value. If this setting is set toTrue
the MIP with the smallest purview is chosen; otherwise, the one with largest purview is chosen.
-
USE_SMALL_PHI_DIFFERENCE_FOR_CES_DISTANCE
default=False
If set to
True
, the distance between cause-effect structures (when computing aSystemIrreducibilityAnalysis
) is calculated using the difference between the sum of \(\varphi\) in the cause-effect structures instead of the extended EMD.
-
SYSTEM_CUTS
default='3.0_STYLE'
,values=['3.0_STYLE', 'CONCEPT_STYLE']
If set to
'3.0_STYLE'
, then traditional IIT 3.0 cuts will be used when computing \(\Phi\). If set to'CONCEPT_STYLE'
, then experimental concept-style system cuts will be used instead.
-
log
() Log current settings.
-