Configuring PyPhi¶
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_POTENTIAL_PURVIEWS': True,
...
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_file('pyphi_config.yml')
Or load a dictionary of configuration values:
>>> pyphi.config.load_dict({'PRECISION': 1})
The config
API¶
- exception pyphi.conf.ConfigurationError¶
- exception pyphi.conf.ConfigurationWarning¶
- pyphi.conf.deprecated(option)¶
- class pyphi.conf.Option(default, values=None, type=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.
- class pyphi.conf.Config(on_change=None)¶
Base configuration object.
See
PyphiConfig
for usage.- classmethod options()¶
Return a dictionary of the
Option
objects for this config.
- defaults()¶
Return the default values of this configuration.
- load_dict(dct)¶
Load a dictionary of configuration values.
- load_file(filename)¶
Load config from a YAML file.
- to_yaml(filename)¶
Write config to a YAML file.
- snapshot()¶
Return a snapshot of the current values of this configuration.
- to_dict()¶
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 ...
- diff(other)¶
Return differences between this configuration and another.
- Returns:
A tuple of two dictionaries. The first contains the differing values of this configuration; the second contains those of the other.
- Return type:
tuple[dict]
- pyphi.conf.configure_logging(conf)¶
Reconfigure PyPhi logging based on the current configuration.
- pyphi.conf.on_change_distinction_phi_normalization(obj)¶
- class pyphi.conf.PyphiConfig(on_change=None)¶
pyphi.config
is an instance of this class.- IIT_VERSION¶
default=4.0
The version of the theory to use.
- 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.
- REPERTOIRE_DISTANCE¶
default='GENERALIZED_INTRINSIC_DIFFERENCE'
The measure to use when computing distances between repertoires and concepts. A full list of currently installed measures is available by calling
print(pyphi.distance.measures.all())
. Note that some measures cannot be used for calculating \(\Phi\) because they are asymmetric.Custom measures can be added using the
pyphi.distance.measures.register
decorator. For example:from pyphi.metrics.distribution import measures @measures.register('ALWAYS_ZERO') def always_zero(a, b): return 0
This measure can then be used by setting
config.REPERTOIRE_DISTANCE = 'ALWAYS_ZERO'
.If the measure is asymmetric you should register it using the
asymmetric
keyword argument. Seedistance
for examples.
- REPERTOIRE_DISTANCE_INFORMATION¶
default='GENERALIZED_INTRINSIC_DIFFERENCE'
The repertoire distance used for evaluating information specified by a mechanism (i.e., finding the maximal state with respect to a purview).
- CES_DISTANCE¶
default='SUM_SMALL_PHI'
The measure to use when computing distances between cause-effect structures.
See documentation for
config.REPERTOIRE_DISTANCE
for more information on configuring measures.
- ACTUAL_CAUSATION_MEASURE¶
default='PMI'
The measure to use when computing the pointwise information between state probabilities in the actual causation module.
See documentation for
config.REPERTOIRE_DISTANCE
for more information on configuring measures.
- PARALLEL¶
default=True
Global switch to turn off parallelization: if
False
, parallelization is never used, regardless of parallelization settings for individual options; otherwise parallelization is determined by those settings.
- PARALLEL_COMPLEX_EVALUATION¶
default={'parallel': True, 'sequential_threshold': 16, 'chunksize': 64, 'progress': True}
Controls parallel evaluation of candidate systems within a network.
- PARALLEL_CUT_EVALUATION¶
default={'parallel': True, 'sequential_threshold': 1024, 'chunksize': 4096, 'progress': True}
Controls parallel evaluation of system partitions.
- PARALLEL_CONCEPT_EVALUATION¶
default={'parallel': True, 'sequential_threshold': 64, 'chunksize': 256, 'progress': True}
Controls parallel evaluation of candidate mechanisms.
- PARALLEL_PURVIEW_EVALUATION¶
default={'parallel': True, 'sequential_threshold': 64, 'chunksize': 256, 'progress': True}
Controls parallel evaluation of candidate purviews.
- PARALLEL_MECHANISM_PARTITION_EVALUATION¶
default={'parallel': True, 'sequential_threshold': 1024, 'chunksize': 4096, 'progress': True}
Controls parallel evaluation of mechanism partitions.
- PARALLEL_RELATION_EVALUATION¶
default={'parallel': True, 'sequential_threshold': 1024, 'chunksize': 4096, 'progress': True}
Controls parallel evaluation of relations.
Only applies if RELATION_COMPUTATION = ‘CONCRETE’.
- NUMBER_OF_CORES¶
default=-1
Controls the number of CPU cores used in parallel evaluation. Negative numbers count backwards from the total number of available cores, with
-1
meaning 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.
- RAY_CONFIG¶
default={}
Keyword arguments to
ray.init()
. Controls the initialization of the Ray cluster used for parallelization / distributed computation.
- 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.
- REDIS_CACHE¶
default=False
Specifies whether to use Redis to cache
MaximallyIrreducibleCauseOrEffect
.
- REDIS_CONFIG¶
default={'host': 'localhost', 'port': 6379, 'db': 0, 'test_db': 1}
Configure the Redis database backend. These are the defaults in the provided
redis.conf
file.
- WELCOME_OFF¶
default=False
Specifies whether to suppress the welcome message when PyPhi is imported.
Alternatively, you may suppress the message by setting the environment variable
PYPHI_WELCOME_OFF
to any value in your shell:export PYPHI_WELCOME_OFF='yes'
The message will not print if either this option is
True
or the environment variable is set.
- LOG_FILE¶
default='pyphi.log'
,on_change=configure_logging
Controls the name of the log file.
- LOG_FILE_LEVEL¶
default='INFO'
,values=[None, 'CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG', 'NOTSET']
,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'
,values=[None, 'CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG', 'NOTSET']
,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.
- 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=13
If
REPERTOIRE_DISTANCE
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 than10**(-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='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. 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.
Finally, if set to
'ALL'
, all possible partitions will be tested.You can experiment with custom partitioning strategies using the
pyphi.partition.partition_types.register
decorator. For example:from pyphi.models import KPartition, Part from pyphi.partition import partition_types @partition_types.register('SINGLE_NODE') def single_node_partitions(mechanism, purview, node_labels=None): for element in mechanism: element = tuple([element]) others = tuple(sorted(set(mechanism) - set(element))) part1 = Part(mechanism=element, purview=()) part2 = Part(mechanism=others, purview=purview) yield KPartition(part1, part2, node_labels=node_labels)
This generates the set of partitions that cut connections between a single mechanism element and the entire purview. The mechanism and purview of each
Part
remain undivided - only connections between parts are severed.You can use this new partititioning scheme by setting
config.PARTITION_TYPE = 'SINGLE_NODE'
.See
partition
for more examples.
- SYSTEM_PARTITION_INCLUDE_COMPLETE¶
default=False
Whether to include the complete partition in partition set.
Currently only applies to “SET_UNI/BI”.
- SYSTEM_PARTITION_TYPE¶
default='SET_UNI/BI'
Controls the system partitioning scheme.
- DISTINCTION_PHI_NORMALIZATION¶
default='NUM_CONNECTIONS_CUT'
,values=['NONE', 'NUM_CONNECTIONS_CUT']
,on_change=on_change_distinction_phi_normalization
Controls how distinction \(\varphi\) values are normalized for determining the MIP.
- RELATION_COMPUTATION¶
default='CONCRETE'
,values=['CONCRETE', 'ANALYTICAL']
Controls how relations are computed.
- STATE_TIE_RESOLUTION¶
default='PHI'
Controls how ties among states are resolved.
NOTE: Operation is max.
- MIP_TIE_RESOLUTION¶
default=['NORMALIZED_PHI', 'NEGATIVE_PHI']
Controls how ties among mechanism partitions are resolved.
NOTE: Operation is min; with the default values, the minimum normalized phi is taken, then in case of ties, the maximal un-normalized phi is taken.
- PURVIEW_TIE_RESOLUTION¶
default='PHI'
Controls how ties among purviews are resolved.
NOTE: Operation is max.
- 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.
- pyphi.conf.validate_combinations(config, options, valid_combinations={}, invalid_combinations={})¶
- pyphi.conf.validate(config)¶
- pyphi.conf.atomic_write_yaml(data, path)¶
- pyphi.conf.write_to_cache(config)¶
- pyphi.conf.on_change_global(config)¶
- pyphi.conf.on_driver()¶
- pyphi.conf.fallback(*args)¶
Return the first argument that is not
None
.
- pyphi.conf.parallel_kwargs(option_kwargs, **user_kwargs)¶
Return the kwargs for a parallel function call.
Applies user overrides to the global configuration.