Scoped config

A set_*! function replaces the global default of one setting of the package in one atomic step. A with_* function changes the setting for the duration of one call, and restores it after. The tasks that the call starts see the change too. The functions are public and not exported, so call them as PortfolioOptimisers.set_resource_limits!.

Base.getindex — Method
getindex(cfg::ScopedConfig)

Read the active value of a ScopedConfig. Inside a with_* block it is the innermost task-scoped override. In other code it is the global default, which the function reads atomically.

Algorithm

  1. Read cfg.scoped[], the innermost task-scoped override. It is nothing outside every with_* block.
  2. When step 1 gives nothing, read cfg.default atomically.

Returns

  • x::T: The active value of the configuration.

Related

source
PortfolioOptimisers.set_resource_limits! — Function
set_resource_limits!(; max_n_sim::Integer, max_n_subsets::Integer,
                     max_frontier::Integer, max_bins::Integer,
                     max_hop_count::Integer, max_search_grid::Integer,
                     max_ep_grid::Integer)

Set the global default of the resource caps of RESOURCE_LIMITS.

Raise the caps for a large run that a program configured, on a machine with enough memory for it. Lower them to accept less untrusted input. A keyword that the caller omits keeps its current default. The store is atomic, as ScopedConfig states. For a temporary, task-scoped override, usewith_resource_limits.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
  2. Build a ResourceLimits from the seven keywords. The validation below runs in that constructor.
  3. Store it as the global default of RESOURCE_LIMITS through set_default!.

Arguments

  • max_n_sim::Integer: The maximum n_sim that the uncertainty-set estimators accept.
  • max_n_subsets::Integer: The maximum n_subsets that the subset-resampling estimators accept.
  • max_frontier::Integer: The maximum N that one Frontier accepts, and the maximum number of sweep points over all swept bounds.
  • max_bins::Integer: The maximum bins that the mutual-information estimators accept.
  • max_hop_count::Integer: The maximum n that HopCount accepts, as a stated value or as the value that a rule resolves.
  • max_search_grid::Integer: The maximum number of candidates in the grid of a search cross-validation.
  • max_ep_grid::Integer: The maximum K that the grid formulations of the entropic and relativistic value-at-risk views accept.

Validation

Returns

  • lims::ResourceLimits: The new global default.

Related

source
PortfolioOptimisers.with_resource_limits — Function
with_resource_limits(f; max_n_sim::Integer = RESOURCE_LIMITS[].max_n_sim,
                     max_n_subsets::Integer = RESOURCE_LIMITS[].max_n_subsets,
                     max_frontier::Integer = RESOURCE_LIMITS[].max_frontier,
                     max_bins::Integer = RESOURCE_LIMITS[].max_bins,
                     max_hop_count::Integer = RESOURCE_LIMITS[].max_hop_count,
                     max_search_grid::Integer = RESOURCE_LIMITS[].max_search_grid,
                     max_ep_grid::Integer = RESOURCE_LIMITS[].max_ep_grid)

Run f() with an override of the resource caps of RESOURCE_LIMITS for the dynamic extent of the call. The previous caps come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.

Use it to raise a cap for one large run, while other concurrent work keeps its caps. The library reads a cap where it resolves the value. It reads the caps on n_sim, N, bins and K when the caller constructs the estimator. It reads the cap on n_subsets when the optimisation resolves its schedule, which can be a TimeDependent. Put this call around the constructor call for the first four caps, and around the optimise call for n_subsets.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
  2. Build a ResourceLimits from the seven keywords. The validation below runs in that constructor.
  3. Run f() with RESOURCE_LIMITS bound to that value through with_config.

Arguments

  • f: The zero-argument function to run under the override.
  • max_n_sim::Integer: The maximum n_sim that the uncertainty-set estimators accept.
  • max_n_subsets::Integer: The maximum n_subsets that the subset-resampling estimators accept.
  • max_frontier::Integer: The maximum N that one Frontier accepts, and the maximum number of sweep points over all swept bounds.
  • max_bins::Integer: The maximum bins that the mutual-information estimators accept.
  • max_hop_count::Integer: The maximum n that HopCount accepts, as a stated value or as the value that a rule resolves.
  • max_search_grid::Integer: The maximum number of candidates in the grid of a search cross-validation.
  • max_ep_grid::Integer: The maximum K that the grid formulations of the entropic and relativistic value-at-risk views accept.

Validation

Returns

  • The value that f() returns.

Related

source
PortfolioOptimisers.set_compact_show! — Function
set_compact_show!(x::Bool)
set_compact_show!(n::Integer)

Configure whether @define_pretty_show collapses large nested structs.

  • set_compact_show!(false): Turn the collapse off, so that each struct prints in full.
  • set_compact_show!(true): Turn the collapse on, with a budget that the size of the terminal sets.
  • set_compact_show!(n): Turn the collapse on, with a fixed line budget n.

The collapse applies only to output with a limited height, where get(io, :limit, false) is true. The interactive REPL is such output. Output with no limit, such as string, repr and a write to a file, always prints in full. The documentation build turns the collapse off, so that the rendered docs show each field. A single call can override the global setting with the :po_compact IO property, which takes false, true or an Int.

The function sets the global default in one atomic store, as ScopedConfig states. For a temporary, task-scoped override, use with_compact_show.

Algorithm

  1. Widen an Integer argument to Int. The two methods then store one of the two members of the stored union, and never a third integer type. A Bool does not change.
  2. Store the value as the global default of COMPACT_SHOW through set_default!.

Arguments

  • x::Bool: false turns the collapse off. true turns it on, with the automatic budget.
  • n::Integer: The fixed line budget, which the function stores as an Int.

Returns

  • x::Union{Bool, Int}: The stored setting.

Related

source
PortfolioOptimisers.with_compact_show — Function
with_compact_show(f, x::Bool)
with_compact_show(f, n::Integer)

Run f() with the collapse setting of COMPACT_SHOW set to x or n for the dynamic extent of the call. The previous setting comes back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change.

Algorithm

  1. Widen an Integer argument to Int, as set_compact_show! does. A Bool does not change.
  2. Run f() with COMPACT_SHOW bound to that value through with_config.

Arguments

  • f: The zero-argument function to run under the override.
  • x::Bool: false turns the collapse off. true turns it on, with the automatic budget.
  • n::Integer: The fixed line budget, which the function stores as an Int.

Returns

  • The value that f() returns.

Related

source
PortfolioOptimisers.set_show_nothing_fields! — Function
set_show_nothing_fields!(x::Bool)
set_show_nothing_fields!(name::Symbol, x::Union{Nothing, Bool})

Configure whether @define_pretty_show renders a field that holds nothing.

  • set_show_nothing_fields!(false): Hide a nothing field, for every type that no per-name entry names. This is the package default.
  • set_show_nothing_fields!(true): Print a nothing field, for every type that no per-name entry names.
  • set_show_nothing_fields!(:SimpleVariance, false): Hide the nothing fields of every type with the name SimpleVariance, whatever the global switch holds.
  • set_show_nothing_fields!(:SimpleVariance, true): Print every declared field of every type with the name SimpleVariance, also a field that its own show_fields method hides.
  • set_show_nothing_fields!(:SimpleVariance, nothing): Remove the per-name entry, so that the type again obeys the global switch and its own show_fields method.

The per-name form takes a name and not a type, because the preferences that load at start are TOML, and TOML holds no types. The name is the name of the type without its module, so two types with one name in two modules share one entry. The function accepts a name that matches no type, and the entry then has no effect. A type outside the package can also print through @define_pretty_show, so the function cannot refuse an unknown name.

The function sets the global default in one atomic store, as ScopedConfig states. For a temporary, task-scoped override, use with_show_nothing_fields.

Algorithm

  1. Read the current global default of SHOW_NOTHING_FIELDS atomically. The function does not read a scoped override, so the call changes the global default alone.
  2. Build the new ShowNothingFields. The one-argument form keeps the per-name table and replaces the global switch. The two-argument form keeps the global switch, and copies the table with one entry set or removed.
  3. Store it as the global default through set_default!.

Arguments

  • x::Bool: false hides a nothing field, and true prints it.
  • name::Symbol: The name of a type, without its module.
  • x::Union{Nothing, Bool}: In the per-name form, the entry to set, or nothing to remove the entry.

Returns

  • cfg::ShowNothingFields: The new global default.

Related

source
PortfolioOptimisers.with_show_nothing_fields — Function
with_show_nothing_fields(f, x::Bool)
with_show_nothing_fields(f, name::Symbol, x::Union{Nothing, Bool})

Run f() with an override of the SHOW_NOTHING_FIELDS setting for the dynamic extent of the call. The previous setting comes back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. The part of the setting that the call does not name comes from the active value, so a nested override adds to the override around it.

Algorithm

  1. Read the active value of SHOW_NOTHING_FIELDS. A nested override then starts from the override around it, and not from the global default.
  2. Build the override as set_show_nothing_fields! does. The one-argument form replaces the global switch and keeps the per-name table. The two-argument form keeps the global switch, and copies the table with one entry set or removed.
  3. Run f() with SHOW_NOTHING_FIELDS bound to that value through with_config.

Arguments

  • f: The zero-argument function to run under the override.
  • x::Bool: false hides a nothing field, and true prints it.
  • name::Symbol: The name of a type, without its module.
  • x::Union{Nothing, Bool}: In the per-name form, the entry to set, or nothing to remove the entry.

Returns

  • The value that f() returns.

Related

source
PortfolioOptimisers.set_string_distance! — Function
set_string_distance!(; dist::StringDistances.StringDistance, min_score::Real)

Set the global default of the fuzzy-suggestion settings that did_you_mean reads. The store is atomic, as ScopedConfig states. A keyword that the caller omits keeps its current default. For a temporary, task-scoped override, use with_string_distance.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
  2. Build a StringDistanceConfig from the two keywords. The validation below runs in that constructor.
  3. Store it as the global default of STRING_DISTANCE through set_default!.

Arguments

  • dist::StringDistances.StringDistance: The distance that ranks the candidate names, for example StringDistances.Levenshtein(), StringDistances.DamerauLevenshtein() or StringDistances.JaroWinkler().
  • min_score::Real: The minimum normalised similarity in (0, 1] that gives a suggestion. A value above 1 turns all suggestions off.

Validation

  • min_score > 0. StringDistanceConfig checks it. A threshold that is not positive admits every candidate with a nonzero similarity.

Returns

  • cfg::StringDistanceConfig: The new global default.

Related

source
PortfolioOptimisers.with_string_distance — Function
with_string_distance(f; dist::StringDistances.StringDistance = STRING_DISTANCE[].dist,
                     min_score::Real = STRING_DISTANCE[].min_score)

Run f() with an override of the fuzzy-suggestion settings that did_you_mean reads, for the dynamic extent of the call. The previous settings come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.

Put this call around a meta-optimiser run, with min_score above 1, to stop the suggestions in its inner loops. Other concurrent work keeps its suggestions.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
  2. Build a StringDistanceConfig from the two keywords. The validation below runs in that constructor.
  3. Run f() with STRING_DISTANCE bound to that value through with_config.

Arguments

  • f: The zero-argument function to run under the override.
  • dist::StringDistances.StringDistance: The distance that ranks the candidate names.
  • min_score::Real: The minimum normalised similarity in (0, 1] that gives a suggestion. A value above 1 turns all suggestions off.

Validation

Returns

  • The value that f() returns.

Related

source
PortfolioOptimisers.set_equation_limits! — Function
set_equation_limits!(; max_length::Integer, max_depth::Integer)

Set the global default of the equation-parser resource caps of EQUATION_LIMITS.

Raise the caps for a large constraint set that a program wrote. Lower them to accept less untrusted input. A keyword that the caller omits keeps its current default. The store is atomic, as ScopedConfig states. For a temporary, task-scoped override, usewith_equation_limits.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
  2. Build an EquationLimits from the two keywords. The validation below runs in that constructor.
  3. Store it as the global default of EQUATION_LIMITS through set_default!.

Arguments

  • max_length::Integer: The maximum length of an equation string that the library passes to Meta.parse.
  • max_depth::Integer: The maximum depth of an expression tree that the Expr form of parse_equation accepts.

Validation

Returns

  • lims::EquationLimits: The new global default.

Related

source
PortfolioOptimisers.with_equation_limits — Function
with_equation_limits(f; max_length::Integer = EQUATION_LIMITS[].max_length,
                     max_depth::Integer = EQUATION_LIMITS[].max_depth)

Run f() with an override of the equation-parser resource caps of EQUATION_LIMITS for the dynamic extent of the call. The previous caps come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.

Use it to lower the caps around one batch of untrusted constraint strings, or to raise them for one large constraint set that a program wrote. Other concurrent work keeps its caps.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
  2. Build an EquationLimits from the two keywords. The validation below runs in that constructor.
  3. Run f() with EQUATION_LIMITS bound to that value through with_config.

Arguments

  • f: The zero-argument function to run under the override.
  • max_length::Integer: The maximum length of an equation string that the library passes to Meta.parse.
  • max_depth::Integer: The maximum depth of an expression tree that the Expr form of parse_equation accepts.

Validation

Returns

  • The value that f() returns.

Related

source
PortfolioOptimisers.set_log_limits! — Function
set_log_limits!(; max_warn::Union{Nothing, Integer}, max_info::Union{Nothing, Integer},
                max_debug::Union{Nothing, Integer})

Set the global default of the caps of LOG_LIMITS on the repeats of one log site.

Set a cap to limit how many times each site of that level logs one _id. Set it to nothing to let each site keep its own limit. A keyword that the caller omits keeps its current default. The store is atomic, as ScopedConfig states. For a temporary, task-scoped override, usewith_log_limits.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
  2. Build a LogLimits from the three keywords. The validation below runs in that constructor.
  3. Store it as the global default of LOG_LIMITS through set_default!.

Arguments

  • max_warn: The maximum number of repeats of one _id at one @warn site, or nothing.
  • max_info: The maximum number of repeats of one _id at one @info site, or nothing.
  • max_debug: The maximum number of repeats of one _id at one @debug site, or nothing.

Validation

  • Each cap is nothing or a positive integer. LogLimits checks it.

Returns

  • lims::LogLimits: The new global default.

Related

source
PortfolioOptimisers.with_log_limits — Function
with_log_limits(f; max_warn::Union{Nothing, Integer} = LOG_LIMITS[].max_warn,
                max_info::Union{Nothing, Integer} = LOG_LIMITS[].max_info,
                max_debug::Union{Nothing, Integer} = LOG_LIMITS[].max_debug)

Run f() with an override of the caps of LOG_LIMITS on the repeats of one log site, for the dynamic extent of the call. The previous caps come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.

Use it to reduce the log of one long cross-validation, while other concurrent work keeps its log. A logger counts the repeats of an _id for as long as the logger exists. A site that reached its limit inside the block thus logs nothing after the block, under the same logger.

Algorithm

  1. Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
  2. Build a LogLimits from the three keywords. The validation below runs in that constructor.
  3. Run f() with LOG_LIMITS bound to that value through with_config.

Arguments

  • f: The zero-argument function to run under the override.
  • max_warn: The maximum number of repeats of one _id at one @warn site, or nothing.
  • max_info: The maximum number of repeats of one _id at one @info site, or nothing.
  • max_debug: The maximum number of repeats of one _id at one @debug site, or nothing.

Validation

  • Each cap is nothing or a positive integer. LogLimits checks it.

Returns

  • The value that f() returns.

Related

source