API documentation

timbre.timbre.c_to_f(temp)

Convert Celsius to Fahrenheit.

Parameters

temp (int or float or tuple or list or np.ndarray) – Temperature in Celsius

Returns

Temperature in Fahrenheit

Return type

int or float or list or np.ndarray

timbre.timbre.calc_binary_schedule(datesecs, state1, state2, t_dwell1, t_dwell2, msid, model_spec, init, duration=2592000.0, t_backoff=1725000.0, pseudo=None)

Simulate a schedule that switches between two states

This runs the model over a “binary” schedule. This function is intended to be used to optimize the t_dwell2 parameter so that the predicted temperature during the last t_backoff number of seconds reaches a limit within a tolerance (limit used and specified in a different function).

Parameters

  • datesecs (float or int) – Date for start of simulation, in seconds from ‘1997:365:23:58:56.816’ (cxotime.CxoTime epoch)

  • state1 (dict) – States for fixed dwell (pitch, roll, ccds, etc.)

  • state2 (dict) – States for variable dwell (pitch, roll, ccds, etc.)

  • t_dwell1 (float or int) – Fixed dwell duration in seconds

  • t_dwell2 (float or int) – Variable dwell duration in seconds (this is the parameter that is optimized)

  • msid (str) – Primary MSID for model being run

  • model_spec (dict, string) – Dictionary of model parameters or file location where parameters can be imported

  • init (dict) – Dictionary of Xija model initialization parameters

  • duration (float, optional) – Duration for entire simulated schedule, defaults to 30 days (in seconds)

  • t_backoff (float, optional) – Duration for tail end of simulated schedule used to determine convergence, defaults to 10 days (in seconds)

  • pseudo (str, optional) – Name of one or more pseudo MSIDs used in the model, if any, only necessary if one wishes to retrieve model results for this pseudo node, if it exists. This currently is not used but kept here as a placeholder.

Returns

  • results (dict) - keys are node names (e.g. ‘aacccdpt’, ‘aca0’), values are Xija model

    component objects, this is the same object returned by run_profile

  • times (np.ndarray) - time values input into Xija (may not exactly match Xija output)

  • state_keys (np.ndarray) - defines state order, with elements matching the time array output

    (may not exactly match Xija output), this defines where to insert what state

Return type

tuple

Notes:

  • Keys in state1 must match keys in state2.

  • Keys in state1 must match Xija component names (e.g. ‘pitch’, ‘ccd_count’, ‘sim_z’)

timbre.timbre.create_opt_fun(datesecs, dwell1_state, dwell2_state, t_dwell1, msid, model_spec, init, t_backoff, duration)

Generate a Xija model function with preset values, for use with an optimization routine.

Parameters

  • datesecs (float or int) – Date for start of simulation, in seconds from ‘1997:365:23:58:56.816’ (cxotime.CxoTime epoch)

  • dwell1_state (dict) – States for fixed dwell (pitch, roll, ccds, etc.)

  • dwell2_state (dict) – States for variable dwell (pitch, roll, ccds, etc.)

  • t_dwell1 (float or int) – Fixed dwell duration in seconds

  • msid (str) – Primary MSID for model being run

  • model_spec (dict, string) – Dictionary of model parameters or file location where parameters can be imported

  • init (dict) – Dictionary of Xija model initialization parameters

  • t_backoff (float, optional) – Duration for tail end of simulated schedule used to determine convergence, defaults to 10 days (in seconds)

  • duration (float, optional) – Duration for entire simulated schedule, defaults to 30 days (in seconds)

Returns

Function generated from specified parameters, to be passed to optimization routine

Return type

function

Notes:

  • Keys in state1 must match keys in state2.

  • Keys in state1 must match Xija component names (e.g. ‘pitch’, ‘ccd_count’, ‘sim_z’)

timbre.timbre.f_to_c(temp)

Convert Fahrenheit to Celsius.

Parameters

temp (int or float or tuple or list or np.ndarray) – Temperature in Fahrenheit

Returns

Temperature in Celsius

Return type

int or float or list or np.ndarray

timbre.timbre.find_second_dwell(date, dwell1_state, dwell2_state, t_dwell1, msid, limit, model_spec, init, limit_type='max', duration=2592000, t_backoff=1725000, n_dwells=10, min_dwell=None, max_dwell=None, pseudo=None)

Determine the required dwell time at pitch2 to balance a given fixed dwell time at pitch1, if any exists.

Parameters

  • date (float or int or str) – Date for start of simulation, in seconds from ‘1997:365:23:58:56.816’ (cxotime.CxoTime epoch) or any other format readable by cxotime.CxoTime

  • dwell1_state (dict) – States for fixed dwell (pitch, roll, ccds, etc.)

  • dwell2_state (dict) – States for variable dwell (pitch, roll, ccds, etc.)

  • t_dwell1 (float or int) – Fixed dwell duration in seconds

  • msid (str) – Primary MSID for model being run

  • limit (float) – Temperature limit for primary MSID in model for this simulation

  • model_spec (dict, string) – Dictionary of model parameters or file location where parameters can be imported

  • init (dict) – Dictionary of Xija model initialization parameters

  • limit_type (str, optional) – Type of limit, defaults to ‘max’ (a maximum temperature limit), other option is ‘min’

  • duration (float, optional) – Duration for entire simulated schedule, defaults to 30 days (in seconds)

  • t_backoff (float, optional) – Duration for tail end of simulated schedule used to determine convergence, defaults to 10 days (in seconds)

  • n_dwells (int, optional) – Number of second dwell, t_dwell2, possibilities to run (more dwells = finer resolution)

  • min_dwell (float, optional) – Minimum duration for second dwell, can be used if the user wants to narrow the dwell time search, defaults to 1.0e-6s

  • max_dwell (float, optional) – Maximum duration for second dwell, can be used if the user wants to narrow the dwell time search

  • pseudo (str, optional) – Name of one or more pseudo MSIDs used in the model, if any, only necessary if one wishes to retrieve model results for this pseudo node, if it exists. This currently is not used but kept here as a placeholder.

Returns

Dictionary of results information

Return type

dict

timbre.timbre.get_github_chandra_models_version_info()

Download a list of all tags and branches, along with associated information.

Returns

Dictionrary of all tags and branches, along with associated information.

Return type

dict

timbre.timbre.get_local_model(filename)

Load parameters for a single Xija model.

Parameters

filename (str) – File path to local model specification file

Returns

Model spec as a dictionary, md5 hash of model spec

Return type

tuple

timbre.timbre.load_github_model_specs(version='master')

Load Xija all model parameters for a specified version from https://github.com/sot/chandra_models.

Parameters

version (str) – tag or branch to use

Returns

A dictionary containing the model specifications for all available Xija models for the chandra_models version specified

Return type

dict

Note: This will need to be updated as new models are approved or existing models are renamed.

timbre.timbre.load_model_specs(version=None, local_repository_location=None)

Load Xija model parameters for all available models.

Parameters

  • version (str) – tag or branch to use

  • local_repository_location (str) – location of chandra_models repository, defaults to get_model_spec.REPO_PATH

Returns

A dictionary containing the model specifications for all available Xija models, along with latest commit sha for version specified (or existing branch/tag), branch/tag, and repository state

Return type

dict

Note: This will need to be updated as new models are approved or existing models are renamed.

timbre.timbre.run_profile(times, schedule, msid, model_spec, init, pseudo=None)

Run a Xija model for a given time and state profile.

Parameters

  • times (np.ndarray) – Array of time values, in seconds from ‘1997:365:23:58:56.816’ (cxotime.CxoTime epoch)

  • schedule (dict) – Dictionary of pitch, roll, etc. values that match the time values specified above in times

  • msid (str) – Primary MSID for model being run

  • model_spec (dict or string) – Dictionary of model parameters or file location where parameters can be imported

  • init (dict) – Dictionary of Xija model initialization parameters, can be empty but not recommended

  • pseudo (str or None, optional) – Name of one or more pseudo MSIDs used in the model, if any, only necessary if one wishes to retrieve model results for this pseudo node, if it exists

Returns

Results, keys are node names (e.g. ‘aacccdpt’, ‘aca0’), values are Xija model component objects

Return type

dict

Example:

times = np.array(CxoTime(['2019:001:00:00:00', '2019:001:12:00:00', '2019:002:00:00:00',
                          '2019:003:00:00:00']).secs)
pitch = np.array([150, 90, 156, 156])
schedule = {'pitch': pitch}
model_specs = load_model_specs()
init = {'1dpamzt': 20., 'dpa0': 20., 'eclipse': False, 'roll': 0, 'vid_board': True, 'clocking': True,
        'fep_count': 5, 'ccd_count': 5, 'sim_z': 100000}
results = run_profile(times, pitch, '1dpamzt', model_specs['1dpamzt'], init, pseudo='dpa0')

Note:

Any parameters specified in init will be overwritten by those specified in the body of this function, if they happen to be defined in both places.

timbre.timbre.run_state_pairs(msid, model_spec, init, limit, date, dwell_1_duration, state_pairs, limit_type='max', min_dwell=None, max_dwell=None, n_dwells=10, print_progress=True, shared_data=None)

Determine dwell balance times for a set of cases.

Parameters

  • msid (str) – Primary MSID for model being run

  • model_spec (dict, string) – Dictionary of model parameters or file location where parameters can be imported

  • init (dict) – Dictionary of Xija model initialization parameters

  • limit (float) – Temperature limit for primary MSID in model for this simulation

  • date (float or int or str) – Date for start of simulation, in seconds from ‘1997:365:23:58:56.816’ (cxotime.CxoTime epoch) or any other format readable by cxotime.CxoTime

  • dwell_1_duration (float or int) – Duration in seconds of dwell 1, also viewed as the known or defined dwell duration, for which one wants to find a complementary dwell duration (dwell duration 2)

  • state_pairs (list or tuple) – Iterable of dictionary pairs, where each pair of dictionaries contain dwell1 and dwell2 states, see state_pair section below for further details

  • limit_type (str, optional) – Type of limit, defaults to ‘max’ (a maximum temperature limit), other option is ‘min’

  • min_dwell (float) – Minimum duration for second dwell, can be used if the user wants to narrow the dwell time search, defaults to 1.0e-6s

  • max_dwell (float) – Maximum duration for second dwell, can be used if the user wants to narrow the dwell time search

  • n_dwells (int, optional) – Number of second dwell, t_dwell2, possibilities to run (more dwells = finer resolution)

  • shared_data (multiprocessing.managers.ListProxy, optoinal) – Shared list of results, used when running multiple run_state_pairs threads in parallel via the multiprocessing package

Returns

Structured numpy array of results

Return type

np.ndarray

State Pairs Data Structure:

The state pairs data structure, state_pairs, are pairs of dictionaries specifying the two conditions used for a Timbre simulation. The keys in these dictionaries must match the Xija component names they refer to (e.g. ‘pitch’, ‘ccd_count’, ‘cossrbx_on’, etc.).

State information that does not change from dwell1 to dwell2 can be specified in the model initialization dictionary. init. State information that does change from dwell1 to dwell2 should be specified in the state pairs dictionary described above. Dictionary names for states should match those expected by Xija (e.g. fep_count, roll, sim_z).

Example:

model_init = {'aacccdpt': {'aacccdpt': -7., 'aca0': -7., 'eclipse': False}, }
model_specs = load_model_specs()
date = '2021:001:00:00:00'
t_dwell1 = 20000.
msid = 'aacccdpt'
limit = -7.1
state_pairs = (({'pitch': 144.2}, {'pitch': 154.95}),
               ({'pitch': 90.2}, {'pitch': 148.95}),
               ({'pitch': 50}, {'pitch': 140}),
               ({'pitch': 90}, {'pitch': 100}),
               ({'pitch': 75}, {'pitch': 130}),
               ({'pitch': 170}, {'pitch': 90}),
               ({'pitch': 90}, {'pitch': 170}))
state_pair_dtype = {'pitch', np.float64}

results = run_state_pairs(msid, model_specs[msid], model_init[msid], limit, date, t_dwell1, state_pairs,
    state_pair_dtype)
timbre.timbre.setup_model(msid, t0, t1, model_spec, init)

Create Xija model object

This function creates a Xija model object with initial parameters, if any. This function is intended to create a streamlined method to creating Xija models that can take both single value data and time defined data (e.g. [pitch1, pitch2, pitch3], [time1, time2, time3]), defined in the init dictionary.

Parameters

  • msid (str) – Primary MSID for model; in this case it can be anything as it is only being used to name the model, however keeping the convention to name the model after the primary MSID being predicted reduces confusion

  • t0 (str or float or int) – Start time for model prediction; this can be any format that cxotime.CxoTime accepts

  • t1 (str or float or int) – End time for model prediction; this can be any format that cxotime.CxoTime accepts

  • model_spec (dict, str) – Dictionary of model parameters or file location where parameters can be imported

  • init (dict) – Dictionary of Xija model initialization parameters, can be empty

Return type

xija.model.XijaModel

Example:

model_specs = load_model_specs()
init = {'1dpamzt': 35., 'dpa0': 35., 'eclipse': False, 'roll': 0, 'vid_board': True, 'pitch':155,
        'clocking': True, 'fep_count': 5, 'ccd_count': 5, 'sim_z': 100000}
model = setup_model('1dpamzt', '2019:001:00:00:00', '2019:010:00:00:00', model_specs['1dpamzt'], init)

Notes:

  • This does not run the model, only sets up the model to be run.

  • Any parameters not specified in init will either need to be pulled from telemetry or explicitly defined outside of this function before running the model.

class timbre.balance.Balance(date, model_spec, limit, constant_conditions, margin_factor)

Base class for defining individual thermal balance calculation objects

find_anchor_condition(p_offset, p_limited, anchor_offset_time, limit)

Given a known offset duration, determine the maximum dwell time for the anchor limited pitch.

Parameters

  • p_offset (float) – Anchor offset pitch

  • p_limited (float) – Anchor limited pitch

  • anchor_offset_time (float) – Anchor offset dwell duration (seconds)

  • limit (float) – Thermal limit

generate_balanced_pitch_dwells(datesecs, pitch_1, t_1, pitch_2, t_2_orig, limit, pitch_range)

Calculate the balanced heating and cooling dwell curves seeded by pitch_1 and pitch_2.

Parameters

  • datesecs (float) – Date used for simulation (seconds)

  • pitch_1 (float) – Anchor limited pitch

  • t_1 (float) – Anchor limited dwell duration (seconds)

  • pitch_2 (float) – Anchor offset pitch

  • t_2_orig (float) – Originally calculated anchor offset dwell duration (seconds)

  • limit (float) – Thermal limit

  • pitch_range (iterable (list, numpy.ndarray)) – Pitch values used to define dwell limits

A balanced set of dwell curves are calculated in two steps:

  1. Calculate the offset dwell curve yielded by pitch_1 at t_1.

  2. Use the time calculated in step 1 for pitch_2 with this pitch to determine the limited dwell curve.

class timbre.balance.Balance1DEAMZT(date, model_spec, limit, constant_conditions, margin_factor=0.95)
class timbre.balance.Balance1DPAMZT(date, model_spec, limit, constant_conditions, margin_factor=0.95)
class timbre.balance.Balance1PDEAAT(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.Balance4RT700T(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.BalanceAACCCDPT(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.BalanceFPTEMP_11(date, model_spec, limit, constant_conditions, margin_factor=0.95)
class timbre.balance.BalancePFTANK2T(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.BalancePLINE03T(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.BalancePLINE04T(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.BalancePM1THV2T(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.BalancePM2THV1T(date, model_spec, limit, constant_conditions, margin_factor=1.0)
class timbre.balance.Composite(date, chips, roll, limits, max_dwell=100000, pitch_step=1, model_specs=None)

Generate a composite maximum dwell estimate using all thermal models.

This class can be used to automatically calculate the maximum best-case dwell duration possible for each model at each limited pitch (often heating) by considering the impact each model has on available cooling for all other models. This class also produces the associated offset (often cooling) dwell durations that can support the limited dwell durations produced for each model.

Example:

from timbre import Composite, f_to_c

limits = {
    "fptemp_11": -112.0,
    "1dpamzt": 37.5,
    "1deamzt": 37.5,
    "1pdeaat": 52.5,
    "aacccdpt": -6.5,
    "4rt700t": f_to_c(100.0),
    "pftank2t": f_to_c(110.0),
    "pm1thv2t": f_to_c(210.0),
    "pm2thv1t": f_to_c(210.0),
    "pline03t": f_to_c(50.0),
    "pline04t": f_to_c(50.0),
}

date = "2022:001:00:00:00"
chips = 4
roll = 0

timbre_object = Composite(date, chips, roll, limits, max_dwell=200000, pitch_step=5)
balance_model(msid, model)

Calculate the balanced limited and offset dwell curves for one model.

fill_composite()

Fill in the limited and offset dwell curves after mapping the fundamental dwell balance data.

map_composite()

Use the anchor pitch values to map the fundamental dwell balance data.

timbre.balance.get_limited_results(results, anchor_offset_pitch)

Extract the limited dwell time results.

Parameters

  • results (numpy.ndarray) – Results calculated by generate_balanced_pitch_dwells

  • anchor_offset_pitch (int or float) – offset pitch used to anchor the limited dwell curve

Returns

Numpy array of limited dwell time results

Return type

numpy.ndarray

Note: The returned array is a structured numpy array with column names defined by Timbre and the input conditions.

timbre.balance.get_offset_results(results, anchor_limited_pitch)

Extract the offset dwell time results.

Parameters

  • results (numpy.ndarray) – Results calculated by generate_balanced_pitch_dwells

  • anchor_limited_pitch (int or float) – limited pitch used to anchor the offset dwell curve

Returns

Numpy array of offset dwell time results

Return type

numpy.ndarray

Note: The returned array is a structured numpy array with column names defined by Timbre and the input conditions.