温室センサーが前のチャネルを覚えている

目標

宇宙温室のADCが前のチャネルの値を記憶する現象を、実際のngspiceの波形で分析し、誤差・モデル・収束を区別した比較レポートを作ります。

なぜ重要なのか

前のDC負荷・RC・ADCの単元を終えてから進めてください。Pythonの関数・list・dict・例外・ファイルの読み込みと、指数関数を使います。実際の機器に電圧は印加しません。予想所要時間は120分なので、期限が切れる前に＋時間で延長してください。最大は180分で、セッションが終了するとファイルが消えます。必要なコードとレポートを、別に保管してください。

環境と成果物

成果物は、/root/adc-acquisition/analyze.pyです。Python3とngspice(バージョン42)は、イメージに入っています。外部からのダウンロードや権限の追加は必要ありません。提供される/opt/lab/fixtures/adc_acquisition/simulator.pyのcapture(cfg,新しいフォルダー)は、固定の回路を実際に実行し、新しいフォルダー/trace.tsvのパスを返します。同じフォルダーにinput.cir・config.json・solver.logも残し、既存のフォルダーは上書きしません。分析・判定の正解は提供しません。

波形生成ヘルパーは、理論の回路と同じ入力スイッチモデルを使います。入力は最初high_vで、1.8µsから1.801µsの間に、low_vへ線形に切り替わります。制御パルスは100nsから始まり、立ち上がり/立ち下がりは1ns、ハイレベル幅はacq_s、周期は1µsです。Ronは100Ω、Roffは10¹²Ω、しきい値は0.5V、初期のサンプル電圧は0Vです。high_vは、1つ目のチャネルという名前にすぎず、low_vより低くてもかまいません。

設定の契約

configは、正確にdictであり、以下の8個のキーだけを受け付けます。すべての数値は、bool・文字列・NaN・無限大を拒否します。bitsは正確にint、それ以外はintまたはfloatを受け付けて、floatで返します。

キー	単位と許容範囲
rs_ohm	Ω、100–10000(両端を含む)
cap_f	F、10e-12–40e-12(両端を含む)
acq_s	s、100e-9–350e-9(両端を含む)
dt_s	s、5e-12または2.5e-12
high_v・low_v	V、それぞれ0–vref_v(両端を含む)で、2つの値は互いに異なる
vref_v	V、1–5(両端を含む)。コード幅の換算用で、回路の電源モデルではありません
bits	実際のint、8–16(両端を含む)。コード幅の換算用

波形・観測の契約

read_traceは、通常のファイル、最大256MiB、空行を除いたデータ2–2,000,000行を受け付けます。ヘッダーは、空白で区切ったtime v(vin) v(gate) v(hold)の順です。各行は、有限のfloat4個で、時間は0以上・厳密な増加、最初の時間は1ns以下、最後の時間は3.5µsと、絶対値で1e-15秒以内に等しくなければなりません。不正な内容はValueErrorで、OSのファイルエラーは、そのまま伝えてもかまいません。検証済みのpointsに対するsampleは、全体の検証を呼び出しのたびに繰り返す必要はありません。

observeの観測時刻は、k=0..3について、100e-9+k*1e-6+acq_s+27e-9秒です。目標のリストは、high_v,high_v,low_v,low_vです。各holdの終わりは、min((k+1)*1e-6+50e-9,3.5e-6)秒です。返すキーは、times_s(4つの時刻)、targets_v(4つの目標)、samples_v(4つの保存電圧)、hold_drift_v(各観測からholdの終わりまでの、絶対変化の最大値)です。入力・gate・holdの条件を外れたら、ValueErrorです。波形と設定は変更しません。

予測・判定の契約

predictは、Vnew=Vtarget+(Vold−Vtarget)*exp(−(acq_s+1e-9)/((rs_ohm+100)*cap_f))を、前の結果から引き継ぎます。開始はVold=0、目標は上の4つです。オフの間の有限のリークは、この解析式では無視します。

assessは、observedのsamples_v・targets_vだけを使います。長さ4、boolではない有限の数値と、設定の目標のリストを確認してください。返すキーは、max_model_error_v、model_consistent、error_lsb、decision、all_passです。model_errorは、観測とpredictの最大の絶対差、model_consistentは、100µV以下かどうかのboolです。error_lsbは、各|観測−目標|を、vref_v/(2**bits)で割った4つです。

モデルが不一致なら、decision4つがすべてinvalid_modelです。一致すれば、各絶対電圧誤差eについて、e+10µV≤0.5LSBならpass、e−10µV>0.5LSBならfail、残りはborderlineです。all_passは、4つすべてがpassのときだけTrueです。10µVは、この実験の判定マージン区間であり、実物の計測の不確かさの認証値ではありません。

条件比較とCLIの契約

campaignは、正確にlistの、2–6個の設定を受け取り、すべて検証してから実行します。すべての入力のdt_sは、5e-12でなければなりません。runner(cfg)は、波形ファイルのパスを返す、提供される呼び出しです。各条件で、元の設定のコピーでrunner→analyzeを行い、続けてdt_sだけを2.5e-12に変えたコピーでrunner→analyzeを行います。1つの条件の2回の実行を終えた後に、次の条件を実行し、元の入力は変更しません。実行の例外は、呼び出し側に伝えます。

返す値は、schema=1、runs、candidate_indices、scope='ideal-switched-rc-only'です。runsは入力の順で、各項目にcoarse・fine(それぞれanalyzeのレポート)、difference_v(4つの保存電圧の最大の絶対差)、converged(差≤10µVのbool)を置きます。candidate_indicesは、収束していて、両方のall_passがともにTrueの条件の、0始まりのインデックスのリストです。候補がなければ空のリストで、エラーと混同しません。異なる変数を同時に変えたなら、このリストだけでは、原因別の効果を断定しません。

main(argv)は、設定リストのJSONファイルと、まだ存在しない出力フォルダーのパスの、2つの引数を受け取ります。JSONのすべての設定と、既定のdtを検証してから、出力フォルダーを作ります(親は、すでにある必要があります)。sys.pathに/opt/lab/fixtures/adc_acquisitionを入れて、simulator.captureを読み込みます。runnerの呼び出しごとに、出力フォルダー/run-00、run-01、...の新しいサブフォルダーで、captureを呼び出してください。campaignの結果を、stdoutにJSON1行で出力して、0を返します。引数・設定・ファイル・実行のExceptionは、{"error":"analysis_failed"}の1行と2を返し、tracebackは出力しません。失敗の前に作られた新しい証拠は消しません。importのときはCLIを実行せず、直接実行したときだけ、mainの戻り値で終了します。

ステップ8の提供される例のリストは、/opt/lab/fixtures/adc_acquisition/cases.jsonです。自分で確認するには、以下のように新しいフォルダー名で実行し、レポートと一緒に、input.cir・config.json・solver.log・trace.tsvを見てください。レポートファイルも、既存の資料を上書きしない名前を選びます。

python3 /root/adc-acquisition/analyze.py /opt/lab/fixtures/adc_acquisition/cases.json /root/adc-acquisition/trial-01 > /root/adc-acquisition/report-01.json

ステップ

数値と単位を明示する: config(value)を実装します。以下の8個のキーの型・範囲を検査し、元を変更しない新しいdictを返します。bitsだけintに、それ以外はfloatに正規化し、不正な値はValueErrorです。
最後まで生成された波形だけを読む: read_trace(path)は、以下のTSVの契約を検査して、4つのfloatのtupleを入れたlistを返します。UTF-8・空白区切りのヘッダー、行・サイズ・有限の数値・時間の順序・開始/終了の範囲を確認してください。空行は無視します。波形は直しません。
観測時刻を補間する: sample(points,when,col=3)は、検証済みの波形から、該当する時刻を線形補間します。colは実際のintの1・2・3、whenはboolではない有限の数値で、両端点は許容します。時間範囲の外と、不正な列は、ValueErrorです。
入力・スイッチ・保存電圧を区別する: observe(cfg,points)は、configで検証した後、4つの観測時刻と目標電圧を計算します。観測時のgateの絶対値と、目標に対するvinの差は、それぞれ1µV以下でなければなりません。sample電圧とholdの終わりの電圧の最大の差も、1µV以下でなければなりません。以下の観測dictを返します。
前の取得電圧を引き継ぐ: predict(cfg)は、設定を検証した後、初期0Vから、1つ目のチャネルを2回、2つ目のチャネルを2回取得する再帰式で、4つの電圧のlistを返します。接続時間はacq_s+1ns、抵抗はrs_ohm+100Ωです。
誤差・モデル・境界の判定を分ける: assess(cfg,observed)は、以下の判定の契約どおりに、LSB誤差、解析式との最大の差、モデル一致、4つのサンプルの判定とall_passを返します。観測dictのsamples_vとtargets_vは、有限の数値4個で、目標のリストが設定と違えば、ValueErrorです。
実際のファイルからレポートを作る: analyze(cfg,trace_path)は、config→read_trace→observe→assessをつないで、schema=1、config、observation、assessmentの4つのキーのdictを返します。ファイルの破損は、成功のレポートに変えず、そのまま伝えます。
条件比較と実際のCLIをつなぐ: campaign(configs,runner)とmain(argv)、CLIのエントリーポイントを、以下の契約で実装します。すべての設定を先に検証し、条件ごとに5ps・2.5psの波形をそれぞれ分析して、収束と両方の判定を一緒に確認します。実際のngspiceと、別のCLIプロセスで検査します。

参考

採点は、一時フォルダーの別の波形で関数を検査し、最後のステップは、実際のngspiceと、別のCLIプロセスも実行します。学習者のフォルダーは変更せず、検査専用のフォルダーだけを整理します。例の数字だけを返すと、別の電圧の向きや条件で失敗します。約70万–140万行の波形を扱うので、複数の実行を一度に立ち上げないでください。出力フォルダー1つを保存したまま、結果を確認します。

理想スイッチのRCモデルの中でだけ、候補を選びます。実際のADCの電荷注入・ノイズ・保護回路・温度・非線形性・実際のバッファーの安定度は、検証しません。機器をつないだり、物理的な電圧を印加したりする課題ではありません。

数値と単位を明示する

config(value)を実装します。以下の8個のキーの型・範囲を検査し、元を変更しない新しいdictを返します。bitsだけintに、それ以外はfloatに正規化し、不正な値はValueErrorです。

boolもintのように動作しますが、回路の抵抗値として受け取ってはいけません。計算の前に、単位を秒・ファラド・オームに統一してください。

最後まで生成された波形だけを読む

read_trace(path)は、以下のTSVの契約を検査して、4つのfloatのtupleを入れたlistを返します。UTF-8・空白区切りのヘッダー、行・サイズ・有限の数値・時間の順序・開始/終了の範囲を確認してください。空行は無視します。波形は直しません。

終了コードやファイルの存在だけで、波形が完成したと判断しないでください。過大なファイルは、内容を読む前に、サイズから確認します。

観測時刻を補間する

sample(points,when,col=3)は、検証済みの波形から、該当する時刻を線形補間します。colは実際のintの1・2・3、whenはboolではない有限の数値で、両端点は許容します。時間範囲の外と、不正な列は、ValueErrorです。

近い次の行をそのまま使うことと、2つの行の間を補間することは、違います。範囲の外を、最後の値で埋めないでください。

入力・スイッチ・保存電圧を区別する

observe(cfg,points)は、configで検証した後、4つの観測時刻と目標電圧を計算します。観測時のgateの絶対値と、目標に対するvinの差は、それぞれ1µV以下でなければなりません。sample電圧とholdの終わりの電圧の最大の差も、1µV以下でなければなりません。以下の観測dictを返します。

v(vin)をサンプルの結果として使うと、残留誤差が消えます。時間の式の27nsと、解析式の1nsを、混同しないでください。

前の取得電圧を引き継ぐ

predict(cfg)は、設定を検証した後、初期0Vから、1つ目のチャネルを2回、2つ目のチャネルを2回取得する再帰式で、4つの電圧のlistを返します。接続時間はacq_s+1ns、抵抗はrs_ohm+100Ωです。

周期全体を充電時間に使ったり、毎回0Vに初期化したりすると、別のモデルを計算することになります。

誤差・モデル・境界の判定を分ける

assess(cfg,observed)は、以下の判定の契約どおりに、LSB誤差、解析式との最大の差、モデル一致、4つのサンプルの判定とall_passを返します。観測dictのsamples_vとtargets_vは、有限の数値4個で、目標のリストが設定と違えば、ValueErrorです。

100µVのモデル照合の許容値と、10µVの判定マージン区間は、別の役割です。borderlineを成功に上げないでください。

実際のファイルからレポートを作る

analyze(cfg,trace_path)は、config→read_trace→observe→assessをつないで、schema=1、config、observation、assessmentの4つのキーのdictを返します。ファイルの破損は、成功のレポートに変えず、そのまま伝えます。

目標値・予測値・観測値を区別し、元の波形と元の設定を保存してください。例の数値を返す関数で、代用しないでください。

条件比較と実際のCLIをつなぐ

campaign(configs,runner)とmain(argv)、CLIのエントリーポイントを、以下の契約で実装します。すべての設定を先に検証し、条件ごとに5ps・2.5psの波形をそれぞれ分析して、収束と両方の判定を一緒に確認します。実際のngspiceと、別のCLIプロセスで検査します。

通過した候補は、明示したモデルの中でだけ候補です。実行の失敗を空の成功リストに変えず、以前の出力フォルダーも上書きしないでください。