
BSpice3f5 Version 1.05 (25 Aug 2015)
------------------------------------

What is BSpice3f5?
------------------

The underlying program
----------------------
It follows the last-known 26-bit port of BSpice3f4 for Risc OS by Guy Griffin,
and retains his icon and some of his templates. The binary is now fully 32-bit
compatible and the porting work was done using BeagleBoard hardware and the
Norcroft compiler.

BSpice is short for 'Batch Spice' and was developed at UC Berkeley for the
design and analysis of electronic circuits by mathematical modelling. SPICE is
a powerful tool widely accepted as being the industry standard for doing such
work.
I believe that 3f5 was the last version of SPICE to be made freely available.

The program takes a standard SPICE 'netlist' containing circuit description
and analysis commands, and outputs ascii data in the form of a SPICE 'rawfile',
which can subsequently be analysed to display the predicted performance of the
circuit.

Risc OS front end
-----------------
The underlying command-line program has been given a standard Risc OS front
end in the !BSpice3f5 application to ease the chore of specifying filenames
etc., and allowing it to multitask as the process can sometimes take a while
to complete.

Automating the process
----------------------
!BSpice3f5 can be used with the !SchemEd circuit editor V1.03 or later, in
which case you will not need to use it directly. The circuit editor will
create the SPICE input file from the circuit, start, run and quit !BSpice3f5,
and finally call a plotting application to graph and optionally tart-up the
results in a desktop window.
If using !BSpice3f5 this way, then the rest of this manual is probably of
little relevance - a complete alternative set of FrontEnd resources are
supplied by the SchemEd editor, and only the bspice3f5 binary itself is used
when operating in this 'child' mode.
This necessitates a slightly different application name under the iconbar icon
and is simply 'BSpice' (without the 3f5) when working in child mode.

It is anticipated that the 'child' mode would be the preferred method of
working for all but the most experienced users or those working across
different platforms, and so this stand-alone implementation is supplied 'for
completeness only'.

The SchemEd editor and supporting applications can be obtained from my site,
as can the latest version of !BSpice3f5:
http://hd-audio.orpheusweb.co.uk/soft.html

E-mail bugs/suggestions to: hsdawson@ormail.co.uk
(with something in the subject line to distinguish from spam)

			--------------------------
Using BSpice3f5
---------------
Double-click the !BSpice3f5 icon and the BSpice3f5 icon will appear on the
iconbar.
Clicking SELECT on the icon will show a dialogue for specifying source
filename.
Drag your source file (SPICE netlist) to the dialogue or to the iconbar icon.

Click on the 'Run' button and the analyses requested in the netlist will be
performed, with spooled program output shown in a FrontEnd window (see below).
When the analysis concludes, a SaveAs dialogue will be shown, enabling the
rawfile to be saved or dragged to another application, such as the SimProbe
post-processor which comes with the SchemEd application.

The default output rawfile destination is a file with the same name as the
source but held in a 'raw' directory at the same level as the directory
holding the source. To take advantage of FrontEnd's Auto Save feature, a
simple project layout is necessary when using !BSpice3f5 in 'stand-alone'
mode.
If used via the SchemEd circuit editor, then projects will be managed from
there.

The FrontEnd output window will show the following:

Source filename, followed by any filenames that have been .INCLUDE'd by it.
Program info and copyright message.
SPICE netlist title line.
Each analysis command as it executes, with progress indicated by a row of 10
dots followed by 'done.'.
Rawfile size (in bytes), time/date, and total elapsed time (since invocation).

If the option 'Auto Run' is set ON, then dragging a SPICE netlist to the
iconbar icon will run the program without first showing the Setup dialogue.

You can of course use just the executable 'bspice3f5' from the command-line.

			--------------------------
Project layout for stand-alone use
----------------------------------
An example project shell is supplied with !BSpice3f5, containing a couple of
test netlists and sufficient model definitions for them to run and produce
rawfiles.

This kind of project layout enables use of the Auto Save feature. All you need
is three directories in the same Filer window: "<foo$dir>" in this example.
The names derive from the corresponding DOS extension normally used for that
type of file.

'cir' - to hold your SPICE source (circuit/netlist) files.

'inc' - to hold your SPICE include (library) files.

'raw' - to receive the output rawfiles generated by SPICE.

The layout is rather similar to a standard Risc OS C-programming project
layout.

Note that "<foo$dir>" can to great advantage be an application directory,
allowing you to get a system variable for it's pathname when opened, and
making it portable and copiable.

When you drag one of your source files to !BSpice3f5 and run it, the default
pathname in the rawfile SaveAs dialogue will be to the 'raw' directory and
having the same filename as the source.

i.e. source "<foo$dir>.cir.mycct" will produce rawfile "<foo$dir>.raw.mycct"

			--------------------------
External Resources
------------------
<SpiceResource$Path>
This system path variable is used to specify to SPICE which directories
to search for any files that are .INCLUDE'd in the SPICE netlist.

It's value is set up in the !Run file of !BSpice3f5 and can be altered or
added to as required - max. length allowable 1024 characters.

As supplied, the example project directory, the !SchemEd SPICE library (if
present and seen), and the CSD will be searched (in that order) when used in
'stand-alone' mode.

When used as a 'child' application by the SchemEd circuit editor, the value of
<SpiceResource$Path> will be set from the SchemEd application and not from
these local values.

			--------------------------
Command-line use
----------------
To ease calling from the command-line, you could copy the binary 'bspice3f5'
into !Boot.Library such that you don't need to supply the full pathname.

If you need to .INCLUDE any other files, make sure the directory holding them
is an element of "<SpiceResource$Path>", or that they are in the CSD.
An alternative method is to give the full pathname of the include file in the
.INCLUDE command in the source netlist if this is more convenient.

You will need to set the 'Next' WimpSlot to at least 1500K.

Syntax: bspice3f5 [-d] [delay] [-h] [-p] [-r] [rawfile] [source file]
                                             
[-s] : enables handshaking with SchemEd editor for timing purposes.
            (do not use - for use in 'slaved' mode only).

[-h] : (or no arguments at all) show syntax and program info..

[-p] : if present, shows 'row-of-dots' progress, otherwise %'age;
       only really needed when using !BSpice3f5 front-end, as
       FrontEnd can't print incrementing percentages.

[-r] : mandatory and indicates next item is rawfile pathname.
                                             
[rawfile] : destination pathname for output rawfile.
                                               
[source file] : SPICE input file (netlist) pathname.
                                               
			--------------------------
Program History
---------------

V1.00 (11 Apr 2011)
-------------------
    New port for 26/32-bit hardware direct from Berkeley source. Ported
    using BeagleBoard hardware.

------------------------------------------------------------------------
V1.01 (29 Apr 2011)
-------------------
(1) Fixed limited buffer length for .INCLUDE path system variable
    <SpiceResource$Path> causing crash when extra directory elements
    added to path.

(2) More rigorous command-line argument checking. Previously would output
    nothing in some scenarios. Now issues error report suggesting cause of
    problem.

(3) FrontEnd now produces output rawfile to SaveAs dialogue, rather than
    requiring rawfile pathname to be specified up-front. Setup dialogue now
    has only one icon (for source file).

(4) Fixed progress reporting not working properly during .NOISE analysis
    whenever something specified for 'points-per-summary' parameter.

------------------------------------------------------------------------
V1.02 (12 Jun 2011)
-------------------
    Fixed possibility of fatal crash in progress-reporting code due to
    division by zero when bad analysis parameters supplied. Now supplies
    a default for a zero parameter (only to the progress code) and reports
    the error normally.
    
------------------------------------------------------------------------
V1.03 (06 Sep 2011)
-------------------
(1) Fixed lossy transmission line ('O' device) support not enabled in
    previous versions.
    
(2) Added a '-s' switch to enable handshaking with SchemEd circuit editor
    when operating in 'slaved' mode.

(3) Fixed progress reporting broken whenever 'no. of points' analysis
    parameter supplied in exponential format.
        
------------------------------------------------------------------------
V1.03a (09 Sep 2011)
-------------------
    Fixed negative analysis parameters not being picked up properly by
    progress-reporting code.
    
------------------------------------------------------------------------
V1.03b (10 Sep 2011)
-------------------
    Fixed crash when analysis parameters begin with a decimal point
    character, i.e. when a leading zero not present.
    
------------------------------------------------------------------------
V1.04 (10 Mar 2013)
------------------
    Now shows unfinished ('file_unf') icon during production of output rawfile.
    
------------------------------------------------------------------------
V1.05 (25 Aug 2015)
------------------
Fixes fatal crash of .DC analysis when nested sweep is specified.

------------------------------------------------------------------------

Unresolved issues
-----------------
.DISTO and .SENS analyses crash if attempted, but then again they did in v3f4.
I'm not even 100% sure they're meant to work with the 'B' variant of SPICE.
No huge loss as all the main ones seem OK so far. However, a more polite
refusal to proceed would be a lot better than a fatal crash.

.PZ analysis works OK I think, but needs further evaluation. I've only
had warnings about 'iteration limits' being reached and suchlike so am
assuming it's down to me not having used it before.

.PRINT doesn't work, but didn't work in 3f4 either and is probably redundant anyway since graphical output is available using !SimProbe.


===============================================================================

    +----------------------------------------------------------------------+
    |                                                                      |
    | This text file was converted from a StrongHelp manual on 25 Aug 2015 |
    |                                                                      |
    |             using !StHlp2Txt version 1.10 (8 June 2001)              |
    |                           by Chris Morison                           |
    |                                                                      |
    |               email: organizer@morison.net                           |
    |                 web: http://www.organizer.morison.net/               |
    |                                                                      |
    +----------------------------------------------------------------------+

