Most people encounter this first with transistors. eg. a typical BJT has the following pin assignments:

1. Emitter
2. Base
3. Collector

However, our simulation models have nodes, and each node will correspond to a pin on the schematic and PCB, so we need to make sure that each pin is connected to the right node.

From the datasheet you’ll be able to get the pin assignments – e.g. pin 2 is the Base. Where do you find the ngspice node assignments? It depends on the type of spice model you’re using.

• Built-in .MODEL. These are used for standard components, so the behaviour of the component can be defined with just a few parameters – e.g. for a basic simulation all you need to know about a resistor is the resistance. There are 17 types of model.
• Custom .SUBCKT (Sub-circuit). These can be used for components that don’t fit into the standard categories, or for a complete add-on board.

Which one is it? In KiCad, look at the spice model editor:

.MODEL

To get the information you need, you’ll need to look at the ngspice manual.

This includes the list of 17 standard models (reproduced here):

Go back to KiCad Spice Model Editor

So, now look at the section of the ngspice manual for BJTs:

This tells us that ngspice expects the nodes to be listed in the order collector, base, emitter.

We’ll use this later.

.SUBCKT

Sub-circuits can be easy to figure out, or they can be hard, depending on whether the creator of the model has made sensible choices about the node names.

Look at the KiCad Spice Model Editor – this example is from a manufacturer spice model of an N-channel MOSFET, that has chosen to use .SUBCKT instead of .MODEL:

Alternate Node Sequence

Now we’re ready to fill in the Alternate Node Sequence box in KiCad:

In this you write a list of the pin numbers, separated by spaces, in the correct node sequence.

e.g. for our BJT example we know that the correct node sequence is

collector, base, emmitter

Recall our pin assigments:

1. Emitter
2. Base
3. Collector

So I’ll rewrite the node sequence with the pin number in brackets:

collector (3), base(2), emmitter(1)

Now all we need are the pin numbers, so strip out everything else:

3 2 1

And put that in the Alternate Node Sequence box:

So I’m on the hunt for an offsite backup solution for this server.

This is Linux, so nothing is simple – the solution is divided into two pieces:

• Remote data storage service – to actually hold the data.
• Backup software – to figure out what needs to be uploaded, and keep track of versions and suchlike.

For the remote side I’ve got three real options:

• rsync.net – starts at $10/mo for 400 GB
• Backblaze B2 – starts at $5/mo for 1TB
• Wasabi – starts at $5.99/mo for 1TB

However, although rsync.net looks pretty simple – the price isn’t competitive. Backblaze B2 and Wasabi are similar – the benefit of Wasabi is that the’s no extra charges for downloads – B2 has a 1GB daily download threshold, and you start getting charged if you go over that.

For the backup software. These are the options I’m looking at. Please note that tools like rsync and rclone aren’t backup tools – they’re just for syncing, so don’t manage the versions or encryption

• duplicity
• borg
• restic
• duplicacy
• Duplicati

Duplicacy

I’m going to rule this one out right away it’s not free – I’m only mentioning it because it’s often included in conversations about Linux backup software.

Duplicity

Duplicity has been described as an old-school approach by this Backblaze blog post. That means it’s the model whereby you create a backup of everything – a full backup, then the next time you back up you only back up what’s changed – that’s an incremental backup. This can be space-efficient and fast and easy to understand, but the downside is to do a restore you need the last full backup, and all the incremental backups since then. This then creates headaches about deciding when to create a new full backup and how often to get rid of the old ones. Having said that it’s a respected and reliable tool which supports everything it needs to: Encryption, Compression, Backblaze B2 storage is supported, Wasabi is not.

Restic

The same article describes Restic as the new-school tool – which supports deduplication to save space. There isn’t a version 1.0.0 yet, but it seems to be fairly popular already, and supports B2 storage & Wasabi.

Borg

Borg is also a deduplicating backup software – seems to be a bit less fashionable that restic, a bit more mature. As far as I can tell the key advantage that Borg offers is compression, but can be slower with large respositories and large files because it’s single-threaded. However it doesn’t natively support remote object storage, so needs another tool to upload the data. See this forum post. It has some nice features, like the ability to mount a backup as a FUSE filesystem so you can browse it.

Duplicati

Not sure which type of tool this is. It does support B2 storage, but not Wasabi. Some people have had issues with reliability with it.

Final Thoughts

I’ve gone with restic and Backblaze B2. They can talk to each other directly, but I like the idea of having a local copy of the repo, so I’ve set restic to backup to a portable HDD, the which then is copied to Backblaze. This means I have the offsite copy in case my house burns down but can still get at the data in more mundane scenarios.

This is an issue if you have customised that configuration file on your system – the system doesn’t know whether it should keep your version, use the new one, or something else. So it asks you to decide what to do about it.

I’m using Debian, which uses the dpkg package management system – that name may be unfamiliar, but if you’ve used any of the Debain family (Ubuntu, Mint, MX, elementary etc.) you will have used one of the friendlier wrappers around it: apt or apt-get.

Today, it’s the Collabora Office configuration file that has been updated:

Configuration file '/etc/loolwsd/loolwsd.xml'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it ? Your options are:
    Y or I : install the package maintainer's version
    N or O : keep your currently-installed version
      D    : show the differences between the versions
      Z    : start a shell to examine the situation
 The default action is to keep your current version.
*** loolwsd.xml (Y/I/N/O/D/Z) [default=N] ?

• The first option is self-explanatory – you’ll lose any customizations you’ve made, but that might be OK for you.
• Keeping your currently-installed version is usually OK – well designed software shouldn’t break because it’s missing a line in an old configuration file.

In either case the system will keep a copy of the one you don’t pick, so you can change your mind later. If you choose to use the package mantainer’s version, there will be a copy of your old one with .dpkg-old added to the filename. If you keep you own config file, the package maintainer’s version will be saved alongside it, with .dpkg-dist added to the filename.

• Choosing option D can help you decide – but ultimately doesn’t resolve the situation.
• Option Z is the point of today’s post – this is how you can fix the situation.

Lets hit Z, and this is what I get:

 The default action is to keep your current version.
*** loolwsd.xml (Y/I/N/O/D/Z) [default=N] ? Z
Useful environment variables:
 - DPKG_SHELL_REASON
 - DPKG_CONFFILE_OLD
 - DPKG_CONFFILE_NEW
Type 'exit' when you're done.
root@waldorf:/# 

The system tells you about 3 environment variables that might be useful to help fix the situation. here I’ve use the echo command (with a $ before the environment variable name) to see what’s in them:

root@waldorf:/# echo $DPKG_SHELL_REASON
conffile-prompt
root@waldorf:/# echo $DPKG_CONFFILE_OLD
/etc/loolwsd/loolwsd.xml
root@waldorf:/# echo $DPKG_CONFFILE_NEW
/etc/loolwsd/loolwsd.xml.dpkg-new

DPKG_CONFFILE_PROMPT isn’t much use to us, but the other two are. We can start a program to compare and merge the differences between the two. I’m using Neovim in diff mode – there are lots of otherways of doing this – I’d suggest you do your research and find your preferred merge tool or text editor.

root@waldorf:/# nvim -d $DPKG_CONFFILE_OLD $DPKG_CONFFILE_NEW

I wont to get into the details of how to use [Neo]vim, but if you’re already a vim user and haven’t used diff mode before, these commands will get you started. You can find more info in the documentation.

Note that the last two commands will make the files the same at that point

Modifiy one of the files (I typically modify my old file – pulling the changes from the new one that I want, and leaving the ones that I don’t), then save and exit your text editor or mergetool

Type exit at the prompt, then the system will ask you again what you want to do:

*** loolwsd.xml (Y/I/N/O/D/Z) [default=N] ?

In this case I’ll choose N or O because I’ve made the changes I want to the original config file.

Basic process:

1. Enable hardware assisted virtualization.
2. Set up WSL (Windows Subsystem for Linux)
3. Install Linux into WSL
4. Download and compile Sage
5. Configure JupyterLab
6. Make it easy to start from windows

Enable hardware assisted virtualization

WSL requires that your system supports hardware assisted virtualization (which pretty much all modern systems do), there are 3 things that you need to get it working:

• The CPU must support it
• The motherboard must support it.
• You need to enable it in the EFI (or BIOS)

This article takes you through getting everything sorted out:

https://support.bluestacks.com/hc/en-us/articles/115003174386-How-to-enable-Virtualization-VT-on-Windows-10-for-BlueStacks-4

Set up WSL 2

Follow this guide: https://docs.microsoft.com/en-us/windows/wsl/install-win10

Install and configure Linux:

1. Go to the Microsoft store and install Ubuntu.

Note: If you already have Ubuntu installed, I’d recommend you follow these instructions to set up a separate, clean install for sage: https://hfakhraei.github.io/Install-multiple-instance-of-same-Linux-Distribution-on-WSL

2. Start Ubuntu from the start menu. A command window should pop up.
3. Run these commands to update Ubuntu:

    sudo apt update
    sudo apt upgrade

4. Reboot by going (in Windows) to Services and restarting the LxssManager. You can also shut down all running WSL instances using the command wsl --shutdown in the Windows command prompt or Powershell.
5. If necessary upgrade to the latest release: https://linuxconfig.org/how-to-upgrade-ubuntu-to-20-10

Set up Sage

These instructions are a simplified version of the official documentation: https://doc.sagemath.org/html/en/installation/source.html

1. Start Ubuntu – All the commands in this section should be run on the Ubuntu installation.
2. Install the packages we need to have ready in advance:

sudo apt install bc binutils bzip2 ca-certificates cliquer cmake coinor-cbc coinor-libcbc-dev curl default-jdk dvipng eclib-tools fflas-ffpack ffmpeg flintqs g++ gcc gfan gfortran git glpk-utils gmp-ecm imagemagick latexmk lcalc libatomic-ops-dev libavdevice-dev libboost-dev libbraiding-dev libbrial-dev libbrial-groebner-dev libbz2-dev libcdd-dev libcdd-tools libcliquer-dev libcurl4-openssl-dev libec-dev libecm-dev libffi-dev libfile-slurp-perl libflint-arb-dev libflint-dev libfreetype6-dev libgc-dev libgd-dev libgf2x-dev libgiac-dev libgivaro-dev libglpk-dev libgmp-dev libgsl-dev libiml-dev libisl-dev libjson-perl liblfunction-dev liblrcalc-dev liblzma-dev libm4rie-dev libmongodb-perl libmpc-dev libmpfi-dev libmpfr-dev libnauty-dev libncurses5-dev libntl-dev libopenblas-dev libpari-dev libpcre3-dev libperl-dev libplanarity-dev libppl-dev libpython3-dev libreadline-dev librw-dev libsqlite3-dev libssl-dev libsuitesparse-dev libsvg-perl libsymmetrica2-dev libterm-readkey-perl libterm-readline-gnu-perl libxml2-dev libxml-libxslt-perl libxml-writer-perl libz-dev libzmq3-dev libzn-poly-dev m4 make nauty ninja-build openssl palp pandoc pari-doc pari-elldata pari-galdata pari-galpol pari-gp2c pari-seadata patch perl pkg-config planarity ppl-dev python3 python3-distutils r-base-dev r-cran-lattice sqlite3 sympow tachyon tar texlive texlive-xetex xcas xz-utils yasm

3. Download and extract the source tarball into a subfolder of your home directory

cd ~
wget http://www.mirrorservice.org/sites/www.sagemath.org/src/sage-9.2.tar.gz
tar xvf sage-9.2.tar.gz

4. Start building

cd sage-9.2/
./configure
make

This will take a long time (3 hours on my system)

5. Test sage

./sage

You should get a prompt that looks like this:

┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 9.2, Release Date: 2020-10-24                     │
│ Using Python 3.8.6. Type "help()" for help.                        │
└────────────────────────────────────────────────────────────────────┘
sage:

6. Type exit and press enter to leave.

7. Make the command available from anywhere on this ubuntu system – edit ~/.bashrc and add this line:

alias sage=~/sage-9.2/sage

8. Close ubuntu then reopen it.
9. Try typing sage and verify that it starts.

JupyterLab

1. Install Jupyter Lab and it’s extras:

sage -i jupyterlab_widgets

This also involves compliation from source, so will take a while.

2. When it’s done, try starting the jupyterlab notebook like this:

sage --notebook jupyterlab

You might notice a problem – the list of files only includes those on your linux machine – you probably want the ones on your windows computer. You can do this by navigating to where the windows files are mounted in linux.

3. Try it (fill in your windows username instead of the square brackets):

cd /mnt/c/Documents\ and\ Settings\[your windows username]
sage --notebook jupyterlab

The list of files should now be the ones in that folder on your windows machine.

4. Lets wrap this all in a script for convenience – Create a file called ~/sage_nb.sh and put these lines into it:

#!/bin/bash
cd /mnt/c/Documents\ and\ Settings/[your windows username]
/home/[your linux username]/sage-9.2/sage --notebook jupyterlab

5. We need to make it executable – ie. so linux will run this file like it would run a program:

chmod ug+x sage_nb.sh

6. Now go back to your home directory and try it again:

cd ~
./sage_nb.sh

The JupyterLab server should start, showing your windows files in the browser.

Create windows shortcut

This is a final nicety that lets you start the JupyterLab server in one click:

1. Open Windows explorer, and type %APPDATA%\Microsoft\Windows\Start Menu\Programs
2. Make a copy of any of the program icons – we’ll customise it to do what we want
3. Right-click, and choose properties.
4. On the General tab:
   • Change the name to whatever you want.
5. On the Shortcut tab:
   • Change Target to: ubuntu.exe run ~/sage_nb.sh
   • Change Start in to: %USERPROFILE%
   • Change Run to: Minimised
   • Change the icon if you want – there are plenty of pieces of software that can create a .ico icon file one from an image file.
6. Now hit the start button or key and type the name you gave it. it should appear in the list, and should load the server and fire up your browser when you click on it.

Software versions:

This is what I used when I wrote this post – you might get different results if your versions are significantly different.

• Windows 10 Pro Version 2004 (OS Build 19041.264)
• Ubuntu 20.10 (Originally installed 20.04 as 20.10 was not available in the Windows Store)
• Sage 9.2

Real to Int

r2i_REAL_in (Data type: REAL):

The real number to convert.

r2i_Precision_in (Data Types: UINT8, UINT16, UINT32):

Number of decimal places to add to the fractional part.

r2i_INT_out (Data Types: INT8, INT16, INT32):

this is the integer part of r2i_REAL_in, no matter what the value of r2i_Precision_in is.

r2i_frac_out: (Data Types: INT8, INT16, INT32):

This is the fractional part of r2i_REAL_in, rounded to the specified number of decimal places, multiplied by 10^( r2i_Precision_in ).

There’s a special case when r2i_Precision_in is 0 (ie. round to the nearest integer): when the magnitude of th fractional part is less than 0.5, it will be 0, otherwise it will be 1 or -1, (the same sign as r2i_REAL_in). To get the correctly rounded number, you need to add r2i_frac_out to r2i_INT_out

The behaviour when the number is too big to fit into either of the integers seems to be inconsistent. If r2i_INT_out is an INT32, then it will 2 147 483 647 if r2i_REAL_in is bigger than that, or -2147483648 if r2i_REAL_in is smaller than that. INT16s and INT8s sometimes overflow instead. (i.e. 128 becomes -128 if r2i_INT_out is an INT8), but it doesn’t do this for all values). I’d avoid using this function in this situation if at all possible.

Examples:

Int to Real

i2r_INT_in (Data Types: INT8, INT16, INT32):

Integer part of value. Not actually necessary, because you can do everything without it.

i2r_FRAC_in (Data Types: INT8, INT16, INT32):

This is the only way to populate it the fractional part of the output, but it will also contribute to the fractional part.

i2r_DECPOS_in (Data Types: UINT8, UINT16, UINT32):

This controls how i2r_FRAC_in is intepreted. Values above 7 result in the fractional part being ignored.

i2r_REAL_out (Data type: REAL):

The Real output value. This is calculated as:
i2r_INT_in + i2r_FRAC_in / 10 ^ ( i2r_DECPOS_in )

Examples

Hopefully this quick reference guide should avoid a few more mistakes in future.

Alternatively, check out the full Classical Style Guide